jama

This MCP server provides read-only access to a Jama Connect instance by wrapping the py-jama-rest-client library. It exposes a set of MCP tools that allow clients to fetch Jama data, such as projects, items, and comments, without performing any write operations. The server is designed for local execution and security: you clone the repository, install dependencies locally, and run the server from your environment. When started, it will read Jama credentials from environment variables (either direct client credentials or AWS Parameter Store) and serve read-only MCP endpoints that client MCP tools can invoke. The included test client demonstrates how to call the tools and view their results, making it easier to validate data access and formatting before integrating into a larger workflow.

Prerequisites

• Python 3.12 or higher
• uv (Python virtual environment manager and package installer for local execution)
• Git
• Optional: Docker if you prefer containerized runs
• Optional: AWS credentials if you plan to fetch Jama credentials from AWS Parameter Store

Setup steps

1. Clone the repository

git clone https://github.com/t-j-thomas/jama-mcp-server.git
cd jama-mcp-server

2. Install dependencies and set up a local virtual environment with uv

uv sync

3. Configure environment variables for authentication

• Direct credentials (preferred if you have client_id and client_secret):

export JAMA_URL=https://your-jama-instance.jamacloud.com
export JAMA_CLIENT_ID=your-client-id
export JAMA_CLIENT_SECRET=your-client-secret

• AWS Parameter Store (if not using direct credentials):

export JAMA_URL=https://your-jama-instance.jamacloud.com
export JAMA_AWS_SECRET_PATH=/path/to/jama/secret
export JAMA_AWS_PROFILE=your-aws-profile (optional)

4. Run the server locally (standalone) using uv

uv run python -m jama_mcp_server.server

5. (Optional) Run via Docker

# Build the image
sudo docker build -t jama-mcp-server .
# Run the container with necessary env vars
sudo docker run -i \
  -e JAMA_URL=... \
  -e JAMA_CLIENT_ID=... \
  -e JAMA_CLIENT_SECRET=... \
  -e JAMA_MOCK_MODE=true/false \
  jama-mcp-server

Testing a minimal setup

uv run python test_mcp_client.py

Additional notes: The server is intentionally read-only at this time. If you modify configuration to use AWS Parameter Store, ensure that the running process has the required AWS permissions. If you encounter SSL certificate issues with the Jama Rest Client, you can adjust your local environment or follow the repository guidance for including a local copy of the py-jama-rest-client during a docker build.

Common issues and tips:

• Ensure JAMA_URL is reachable from the host where the MCP server runs.
• If using AWS Parameter Store, verify IAM permissions for the configured profile.
• In mock mode (JAMA_MOCK_MODE=true), the server will return predetermined sample data, which is useful for testing MCP clients without a live Jama instance.
• When running via Docker, the directory mounting and build context should include any necessary local copies referenced by pyproject.toml or uv.lock; if you encounter build errors related to the Jama REST client, follow the certificate workaround described in the README.
• The environment variable names and their usage are defined in the README; ensure you do not leak sensitive credentials in shared logs or configuration files.