MCP 服务器

evergreen-mcp-server

MCP server for MongoDB's Evergreen CI/CD platform, enabling AI assistants to manage projects, analyze builds, and troubleshoot failures via natural language.

README

Evergreen MCP Server

A Model Context Protocol (MCP) server that provides access to the Evergreen CI/CD platform API. This server enables AI assistants and other MCP clients to interact with Evergreen projects, builds, tasks, and other CI/CD resources.

Overview

Evergreen is MongoDB's continuous integration platform. This MCP server exposes Evergreen's functionality through the Model Context Protocol, allowing AI assistants to help with CI/CD operations, project management, and build analysis.

Features

Project Resources: Access and list Evergreen projects and build statuses
Failed Jobs Analysis: Fetch failed jobs and logs for specific commits to help identify CI/CD failures
Unit Test Failure Analysis: Detailed analysis of individual unit test failures with test-specific logs and metadata
Task Log Retrieval: Get detailed logs for failed tasks with error filtering
REST API Log Analysis: Full untruncated task and test logs via REST API with automatic error pattern scanning
Stepback Analysis: Find failed mainline tasks that have undergone stepback bisection
Authentication: Secure OIDC-based authentication via evergreen login
Async Operations: Built on asyncio for efficient concurrent operations
GraphQL + REST Integration: Uses Evergreen's GraphQL API for metadata and REST API for full log content

Quick Start

Step 1: Authenticate with Evergreen

First, authenticate with Evergreen using the CLI. This creates the necessary credentials that the MCP server will use:

evergreen login

This will:

Open your browser for OIDC authentication
Create ~/.evergreen.yml with your credentials
Create ~/.kanopy/token-oidclogin.json with your OIDC token

Note: If you don't have the Evergreen CLI installed, see Evergreen CLI Installation.

Step 2: Configure Your MCP Client

Add the Evergreen MCP server to your AI assistant's MCP configuration. You can use either uv (lightweight, no Docker needed) or Docker.

Option A: Using uv (Recommended)

uv is a fast Python package manager that can run the MCP server directly — no cloning, no virtual environments, no Docker required.

Install uv (if you don't have it):

curl -LsSf https://astral.sh/uv/install.sh | sh

Then add the server to your MCP client config:

Cursor IDE (.cursor/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ]
    }
  }
}

VS Code with MCP Extension (settings.json):

{
  "mcp.servers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ]
    }
  }
}

Note: uvx automatically downloads, caches, and runs the server in an isolated environment. No manual setup needed.

Option B: Using Docker

Cursor IDE (.cursor/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "-e", "SENTRY_ENABLED=true",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

VS Code with MCP Extension (settings.json):

{
  "mcp.servers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${userHome}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${userHome}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Step 3: Start Using It

Once configured, you can ask your AI assistant questions like:

"Show me my recent Evergreen patches"
"What failed in my last patch?"
"Get the logs for this failing task"
"Find stepback failures in the mms project"

That's it! The server will use your evergreen login credentials automatically.

Note: Telemetry is enabled by default to help improve reliability. To disable it, change the arg SENTRY_ENABLED from true to false i.e. -e SENTRY_ENABLED=false. See Telemetry for details.

Alternative Setup Methods

Using API Keys (Legacy)

If you can't use OIDC authentication, you can use API keys instead:

Get your API key from Evergreen (User Settings → API Key)
Configure your MCP client:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "EVERGREEN_USER=your_username",
        "-e", "EVERGREEN_API_KEY=your_api_key",
        "-e", "SENTRY_ENABLED=true",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Local Development Setup

For development or if you prefer not to use Docker:

Clone and install:

git clone https://github.com/evergreen-ci/evergreen-mcp-server.git
cd evergreen-mcp-server
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Configure your MCP client to use the local installation:

{
  "mcpServers": {
    "evergreen": {
      "command": "/path/to/evergreen-mcp-server/.venv/bin/evergreen-mcp-server",
      "args": []
    }
  }
}

Running the Server (Detailed)

The Evergreen MCP server is designed to be used with MCP clients and communicates via stdio by default. This section covers all the ways you can run the server.

Understanding MCP Server Architecture

The MCP server operates as a subprocess spawned by your AI assistant (like Cursor, Claude Desktop, etc.). The assistant communicates with the server through standard input/output (stdio), sending JSON-RPC messages back and forth.

Key concepts:

stdio transport: The server reads from stdin and writes to stdout (default)
HTTP transports: Alternative transports (SSE, streamable-http) for when stdio isn't available
Lifespan management: The client (your AI assistant) manages starting/stopping the server

Method 1: uv (Recommended)

The fastest way to get started — no Docker, no cloning, no virtual environments. uv downloads and runs the server in an isolated environment automatically.

Prerequisites:

Evergreen CLI installed (evergreen login completed)

Install uv (if you don't have it):

curl -LsSf https://astral.sh/uv/install.sh | sh

Configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ]
    }
  }
}

How it works:

uvx fetches the package from GitHub, installs it in an isolated cache, and runs the evergreen-mcp-server entry point
Subsequent runs use the cached version (fast startup)
The server reads credentials from ~/.evergreen.yml and ~/.kanopy/token-oidclogin.json directly (no volume mounts needed)
To force a refresh: uv cache clean

With project configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server",
        "--project-id", "mongodb-mongo-master"
      ]
    }
  }
}

With custom endpoint URLs (optional):

Override the default Evergreen API endpoint URLs via environment variables. This is useful for Kanopy deployments or other environments where the server needs to reach Evergreen over a service mesh instead of the public ingress.

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ],
      "env": {
        "EVERGREEN_OIDC_REST_URL": "https://custom-evergreen.example.com/rest/v2/",
        "EVERGREEN_OIDC_GRAPHQL_URL": "https://custom-evergreen.example.com/graphql/query"
      }
    }
  }
}

Four env vars are available, one per auth-method/endpoint combination:

Variable	Auth Method	Default
`EVERGREEN_OIDC_REST_URL`	OIDC	`https://evergreen.corp.mongodb.com/rest/v2/`
`EVERGREEN_OIDC_GRAPHQL_URL`	OIDC	`https://evergreen.corp.mongodb.com/graphql/query`
`EVERGREEN_API_KEY_REST_URL`	API key	`https://evergreen.mongodb.com/rest/v2/`
`EVERGREEN_API_KEY_GRAPHQL_URL`	API key	`https://evergreen.mongodb.com/graphql/query`

Tip: If your IDE can't find uvx, use the full path (e.g., ~/.local/bin/uvx on macOS/Linux). Run which uvx to find it.

Method 2: Docker with OIDC

This is the most secure and easiest approach for most users.

Prerequisites:

Docker installed and running
Evergreen CLI installed (evergreen login completed)

Configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

With project configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "-e", "EVERGREEN_PROJECT=mongodb-mongo-master",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Method 3: Docker with API Keys

For environments where OIDC isn't available or when using service accounts.

When to use:

Kubernetes/cloud deployments
CI/CD pipelines
Service accounts
Environments where file mounting is difficult

Configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "EVERGREEN_USER=your_username",
        "-e", "EVERGREEN_API_KEY=your_api_key",
        "-e", "EVERGREEN_PROJECT=mongodb-mongo-master",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

⚠️ Security considerations:

API keys in environment variables are visible in process lists
Consider using credential management systems in production
Rotate API keys regularly

Method 4: Local Installation (Development)

Running the server directly from source code for development or customization.

When to use:

Developing the MCP server itself
Testing local changes
Environments without Docker
Maximum control over dependencies

Setup:

# Clone and set up
git clone https://github.com/evergreen-ci/evergreen-mcp-server.git
cd evergreen-mcp-server
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

# Verify installation
evergreen-mcp-server --help

Configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "/absolute/path/to/evergreen-mcp-server/.venv/bin/evergreen-mcp-server",
      "args": []
    }
  }
}

With workspace auto-detection:

{
  "mcpServers": {
    "evergreen": {
      "command": "/path/to/.venv/bin/evergreen-mcp-server",
      "args": ["--workspace-dir", "${workspaceFolder}"]
    }
  }
}

Development workflow:

# Activate environment
source .venv/bin/activate

# Run tests
pytest tests/ -v

# Test with MCP Inspector
npx @modelcontextprotocol/inspector .venv/bin/evergreen-mcp-server

# Make changes to code
# Changes are immediately available due to editable install (pip install -e .)

Method 5: HTTP/SSE Transport

For scenarios where stdio isn't practical, run the server as a standalone HTTP service.

When to use:

Debugging with network inspection tools
Shared server instances
Non-stdio MCP clients
Browser-based AI assistants

Start the server:

# Using Docker
docker run --rm -p 8000:8000 \
  -e EVERGREEN_MCP_TRANSPORT=sse \
  -e EVERGREEN_MCP_HOST=0.0.0.0 \
  -v ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro \
  -v ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro \
  ghcr.io/evergreen-ci/evergreen-mcp-server:latest

# Using local installation
EVERGREEN_MCP_TRANSPORT=sse \
EVERGREEN_MCP_HOST=0.0.0.0 \
EVERGREEN_MCP_PORT=8000 \
evergreen-mcp-server

Client configuration:

{
  "mcpServers": {
    "evergreen": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Transport options:

sse (Server-Sent Events): Best for most HTTP scenarios
streamable-http: Alternative streaming protocol
stdio: Default, for subprocess communication

Building Custom Docker Images

If you need to customize the Docker image:

# Clone the repository
git clone https://github.com/evergreen-ci/evergreen-mcp-server.git
cd evergreen-mcp-server

# Build custom image
docker build -t evergreen-mcp-server:custom .

# Test the custom image
docker run --rm -it \
  -e EVERGREEN_USER=your_username \
  -e EVERGREEN_API_KEY=your_api_key \
  evergreen-mcp-server:custom --help

# Use in MCP configuration
{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
    "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
    "evergreen-mcp-server:custom"
  ]
}

MCP Client Configuration (Detailed)

Comprehensive setup guides for various MCP clients and AI assistants.

Cursor IDE

Location: .cursor/mcp.json in your workspace, or Settings → Features → MCP

Basic configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ],
      "env": {
        "EVERGREEN_PROJECT": "mongodb-mongo-master"
      }
    }
  }
}

Local installation:

{
  "mcpServers": {
    "evergreen": {
      "command": "/Users/yourname/projects/evergreen-mcp-server/.venv/bin/evergreen-mcp-server",
      "args": ["--workspace-dir", "${workspaceFolder}"]
    }
  }
}

Testing the configuration:

Save your .cursor/mcp.json file
Restart Cursor (or reload the window)
Open the MCP panel (View → MCP or Cmd+Shift+P → "MCP")
Verify the Evergreen server shows as "Connected"
Try a test query: "Show me my recent Evergreen patches"

Claude Desktop

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Testing:

Save the config file
Quit Claude Desktop completely
Restart Claude Desktop
Look for the 🔌 icon in the bottom-right corner
Click it to see connected MCP servers
Test with: "List my recent Evergreen patches"

Troubleshooting Claude Desktop:

Server not connecting: Check Docker is running (docker ps)
No 🔌 icon: Verify config file syntax (use a JSON validator)
Permission errors: Ensure credential files exist and are readable
Logs: View logs in Settings → Advanced → View Logs

VS Code with MCP Extension

Prerequisites:

Install the MCP extension from VS Code marketplace

Location: VS Code Settings (JSON) - settings.json

Configuration:

{
  "mcp.servers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${userHome}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${userHome}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ],
      "env": {}
    }
  }
}

Note: VS Code uses ${userHome} instead of ${HOME} for path expansion.

Per-workspace configuration: Create .vscode/settings.json in your workspace:

{
  "mcp.servers": {
    "evergreen": {
      "command": "/path/to/.venv/bin/evergreen-mcp-server",
      "args": ["--workspace-dir", "${workspaceFolder}"],
      "env": {
        "EVERGREEN_PROJECT": "mongodb-mongo-master"
      }
    }
  }
}

Augment Code Assistant

For VS Code:

{
  "augment.mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ],
      "env": {}
    }
  }
}

For JetBrains IDEs: Add to Augment plugin settings:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Using HTTP transport with Augment:

{
  "augment.mcpServers": {
    "evergreen": {
      "url": "http://localhost:8000/sse"
    }
  }
}

GitHub Copilot Chat

Configuration:

{
  "github.copilot.chat.mcp": {
    "servers": {
      "evergreen": {
        "command": "docker",
        "args": [
          "run", "--rm", "-i",
          "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
          "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
          "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
        ]
      }
    }
  }
}

Universal Configuration Pattern

For any MCP-compatible client, follow this pattern:

uv (simplest):

{
  "command": "uvx",
  "args": [
    "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
    "evergreen-mcp-server"
  ]
}

Docker with OIDC:

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "<path-to-token>:/home/evergreen/.kanopy/token-oidclogin.json:ro",
    "-v", "<path-to-config>:/home/evergreen/.evergreen.yml:ro",
    "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
  ]
}

Local installation:

{
  "command": "<absolute-path-to-venv>/bin/evergreen-mcp-server",
  "args": []
}

Path variables by platform:

macOS/Linux: ${HOME} or ~
Windows: ${USERPROFILE} or %USERPROFILE%
VS Code: ${userHome}
Cursor: ${HOME}

Tool Reference

`list_user_recent_patches_evergreen`

Lists recent patches for the authenticated user.

Parameters:

limit (optional): Number of patches to return (default: 10, max: 50)
project_id (optional): Filter by project identifier

Example Usage:

{
  "tool": "list_user_recent_patches_evergreen",
  "arguments": {
    "limit": 10
  }
}

Response Format:

{
  "user_id": "developer@example.com",
  "patches": [
    {
      "patch_id": "507f1f77bcf86cd799439011",
      "description": "Fix authentication bug",
      "status": "failed",
      "create_time": "2025-09-23T10:30:00Z",
      "project_identifier": "mms"
    }
  ]
}

`get_patch_failed_jobs_evergreen`

Retrieves failed jobs for a specific patch with test failure counts.

Parameters:

patch_id (required): Patch identifier
project_id (optional): Evergreen project identifier
max_results (optional): Maximum failed tasks to return (default: 50)

Example Usage:

{
  "tool": "get_patch_failed_jobs_evergreen",
  "arguments": {
    "patch_id": "507f1f77bcf86cd799439011"
  }
}

Response Format:

{
  "patch_info": { "status": "failed" },
  "failed_tasks": [
    {
      "task_id": "task_456",
      "status": "failed",
      "test_info": {
        "failed_test_count": 5
      }
    }
  ]
}

`get_task_logs_evergreen`

Retrieves detailed logs for a specific task with error filtering.

Parameters:

task_id (required): Task identifier
execution (optional): Task execution number (default: 0)
max_lines (optional): Maximum log lines (default: 1000)
filter_errors (optional): Filter for errors only (default: true)

Example Usage:

{
  "tool": "get_task_logs_evergreen",
  "arguments": {
    "task_id": "task_456",
    "filter_errors": true
  }
}

`get_task_test_results_evergreen`

Retrieves detailed unit test results for a task.

Parameters:

task_id (required): Task identifier
execution (optional): Task execution number (default: 0)
failed_only (optional): Only failed tests (default: true)
limit (optional): Maximum test results (default: 100)

Example Usage:

{
  "tool": "get_task_test_results_evergreen",
  "arguments": {
    "task_id": "task_456",
    "failed_only": true
  }
}

`get_task_log_detailed`

Fetches the complete, untruncated task logs via REST API. Returns the full task execution log including timeout handler output, process dumps, and stdout/stderr — content not accessible via the GraphQL get_task_logs_evergreen tool. Automatically scans for error patterns and returns a structured summary with top error terms and example lines when errors are found; returns raw text when no errors are detected.

Parameters:

task_id (required): Task identifier from get_patch_failed_jobs results
execution_retries (optional): Execution number, 0 for first run, 1+ for retries (default: 0)

Example Usage:

{
  "tool": "get_task_log_detailed",
  "arguments": {
    "task_id": "task_456",
    "execution_retries": 0
  }
}

`get_test_results_detailed`

Fetches raw test log content via REST API (stored in S3, not accessible via GraphQL). Automatically scans for error patterns and returns a structured summary. Use this to understand WHY a test failed, not just that it failed.

Parameters:

test_name (required): Test name for S3 log path (e.g., Job0, Job1)
task_id (required): Task identifier from get_patch_failed_jobs results
execution_retries (optional): Execution number (default: 0)
tail_limit (optional): Lines from end of log (default: 100000)

Example Usage:

{
  "tool": "get_test_results_detailed",
  "arguments": {
    "test_name": "Job0",
    "task_id": "task_456",
    "execution_retries": 0
  }
}

`get_stepback_tasks_evergreen`

Finds failed mainline tasks that have undergone stepback bisection.

Parameters:

project_id (required): Evergreen project identifier
limit (optional): Versions to analyze (default: 20)
requesters (optional): Filter by requester type (e.g. ['gitter_request'])
variants (optional): Filter to specific build variants
exclude_variants (optional): Exclude specific build variants

Example Usage:

{
  "tool": "get_stepback_tasks_evergreen",
  "arguments": {
    "project_id": "mongodb-mongo-master",
    "limit": 10,
    "variants": ["enterprise-rhel-80-64-bit"]
  }
}

`get_inferred_project_ids_evergreen`

Discovers which Evergreen projects you've been working on based on recent patches.

Parameters:

max_patches (optional): Patches to scan (default: 50)

Complete Workflow Examples

Workflow 1: Debugging a Failed Patch

Scenario: Your patch failed in CI, and you want to understand why.

Step 1: List Your Recent Patches

Ask your AI assistant: "Show me my recent Evergreen patches"

The assistant calls:

{
  "tool": "list_user_recent_patches_evergreen",
  "arguments": { "limit": 10, "project_id": "mms" }
}

Response shows:

{
  "patches": [
    {
      "patch_id": "abc123",
      "description": "CLOUDP-12345: Fix auth bug",
      "status": "failed",
      "create_time": "2025-01-12T10:30:00Z"
    }
  ]
}

Step 2: Analyze Failed Jobs

Ask: "What failed in patch abc123?"

The assistant calls:

{
  "tool": "get_patch_failed_jobs_evergreen",
  "arguments": { "patch_id": "abc123" }
}

Response shows:

{
  "failed_tasks": [
    {
      "task_id": "task_auth_tests_123",
      "task_name": "auth_unit_tests",
      "build_variant": "ubuntu2004",
      "status": "failed",
      "test_info": {
        "failed_test_count": 3,
        "total_test_count": 150
      }
    }
  ]
}

Step 3: Get Specific Test Failures

Ask: "Show me the failing tests in that task"

The assistant calls:

{
  "tool": "get_task_test_results_evergreen",
  "arguments": {
    "task_id": "task_auth_tests_123",
    "failed_only": true
  }
}

Response shows specific test names, files, and log URLs.

Step 4: Examine Error Logs

Ask: "Get the error logs for that task"

The assistant calls:

{
  "tool": "get_task_logs_evergreen",
  "arguments": {
    "task_id": "task_auth_tests_123",
    "filter_errors": true,
    "max_lines": 100
  }
}

Step 5: AI Analysis

The assistant synthesizes all this information and provides:

Root cause analysis
Suggested fixes
Links to relevant logs
Similar past failures

Workflow 2: Investigating Mainline Failures

Scenario: You want to find recent mainline commit failures that have been bisected via stepback.

Ask: "Find recent stepback failures in the mongodb-mongo-master project for the compile task"

{
  "tool": "get_stepback_tasks_evergreen",
  "arguments": {
    "project_id": "mongodb-mongo-master",
    "limit": 20,
    "variants": ["enterprise-rhel-80-64-bit-compile"]
  }
}

The response shows:

Versions with failures
Tasks that failed
Stepback information (which commits were tested)
Links to investigate further

Workflow 3: Monitoring Team's Patch Status

Scenario: You're on-call and want to check if team members have failing patches.

Ask: "Are there any recent failing patches I should know about?"

The assistant:

Calls list_user_recent_patches_evergreen to get your patches
Checks status of each
For failed patches, calls get_patch_failed_jobs_evergreen
Summarizes failures with severity and urgency

Workflow 4: Comparative Analysis

Scenario: Your test is flaky, and you want to compare multiple failures.

Ask: "Compare the failures in my last 3 patches"

The assistant:

Lists your recent patches
Gets failed jobs for each
Analyzes common patterns
Identifies if it's the same test failing
Suggests if it's a flaky test vs. a real issue

Advanced Configuration

Understanding Evergreen Configuration File

The ~/.evergreen.yml file is your central configuration for Evergreen authentication and project settings.

Basic structure:

user: your.email@example.com
api_key: your_api_key_here
api_server_host: https://evergreen.mongodb.com
ui_server_host: https://spruce.mongodb.com

With OIDC (managed by evergreen login):

user: your.email@example.com
api_server_host: https://evergreen.mongodb.com
ui_server_host: https://spruce.mongodb.com

The OIDC token is stored separately in ~/.kanopy/token-oidclogin.json.

Project Auto-Detection

Configure automatic project detection based on your workspace directory:

user: your.email@example.com
api_key: your_api_key
projects_for_directory:
  /Users/yourname/mongodb: mongodb-mongo-master
  /Users/yourname/mms: mms
  /Users/yourname/atlas-proxy: atlasproxy

How it works:

The MCP server checks your current workspace directory
Matches it against the configured paths
Automatically sets the project context for tool calls
The AI assistant receives this as part of its context

Priority order:

Explicit project_id argument in tool calls
EVERGREEN_PROJECT environment variable
Auto-detected from workspace directory
Project specified in ~/.evergreen.yml (if single project)

Environment Variables Reference

Variable	Type	Description	Example
`EVERGREEN_USER`	string	Username for API key auth	`john.doe@example.com`
`EVERGREEN_API_KEY`	string	API key for authentication	`abc123def456...`
`EVERGREEN_PROJECT`	string	Default project identifier	`mongodb-mongo-master`
`EVERGREEN_API_SERVER`	string	API server URL (advanced)	`https://evergreen.mongodb.com`
`EVERGREEN_OIDC_REST_URL`	string	Override REST base URL for OIDC auth	`https://evergreen.corp.mongodb.com/rest/v2/`
`EVERGREEN_OIDC_GRAPHQL_URL`	string	Override GraphQL endpoint URL for OIDC auth	`https://evergreen.corp.mongodb.com/graphql/query`
`EVERGREEN_API_KEY_REST_URL`	string	Override REST base URL for API key auth	`https://evergreen.mongodb.com/rest/v2/`
`EVERGREEN_API_KEY_GRAPHQL_URL`	string	Override GraphQL endpoint URL for API key auth	`https://evergreen.mongodb.com/graphql/query`
`EVERGREEN_MCP_TRANSPORT`	enum	Transport protocol	`stdio`, `sse`, `streamable-http`
`EVERGREEN_MCP_HOST`	string	HTTP host binding	`0.0.0.0`, `127.0.0.1`
`EVERGREEN_MCP_PORT`	integer	HTTP port	`8000`
`WORKSPACE_PATH`	string	Workspace directory	`/path/to/project`
`SENTRY_ENABLED`	boolean	Enable/disable telemetry (default: true)	`true`, `false`

Command-Line Arguments

All command-line arguments and their usage:

evergreen-mcp-server [OPTIONS]

Options:

--project-id <PROJECT_ID>

Explicitly set the default Evergreen project
Overrides auto-detection and environment variables
Example: --project-id mongodb-mongo-master

--workspace-dir <PATH>

Specify workspace directory for project auto-detection
Useful when running outside the actual workspace
Example: --workspace-dir /path/to/mongodb

--transport <TRANSPORT>

Choose transport protocol
Values: stdio (default), sse, streamable-http
Example: --transport sse

--host <HOST>

Host to bind for HTTP transports
Default: 127.0.0.1 (localhost only)
Use 0.0.0.0 to allow external connections
Example: --host 0.0.0.0

--port <PORT>

Port to listen on for HTTP transports
Default: 8000
Example: --port 9000

--help

Display help information and exit

Usage examples:

# Basic usage (stdio with auto-detection)
evergreen-mcp-server

# Explicit project
evergreen-mcp-server --project-id mms

# HTTP server mode
evergreen-mcp-server --transport sse --host 0.0.0.0 --port 8080

# With workspace detection
evergreen-mcp-server --workspace-dir ~/projects/mongodb

# Combined
evergreen-mcp-server --project-id mms --workspace-dir ~/projects/mms

Advanced Docker Configuration

Custom Networking

Run on a specific Docker network:

docker network create mcp-network

docker run --rm -i \
  --network mcp-network \
  -v ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro \
  -v ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro \
  ghcr.io/evergreen-ci/evergreen-mcp-server:latest

Resource Limits

Limit CPU and memory:

docker run --rm -i \
  --cpus="1.0" \
  --memory="512m" \
  -v ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro \
  -v ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro \
  ghcr.io/evergreen-ci/evergreen-mcp-server:latest

Using Docker Compose

Create docker-compose.yml:

version: '3.8'
services:
  evergreen-mcp:
    image: ghcr.io/evergreen-ci/evergreen-mcp-server:latest
    stdin_open: true
    volumes:
      - ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro
      - ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro
    environment:
      - EVERGREEN_PROJECT=mongodb-mongo-master
      - EVERGREEN_MCP_TRANSPORT=sse
      - EVERGREEN_MCP_HOST=0.0.0.0
      - EVERGREEN_MCP_PORT=8000
    ports:
      - "8000:8000"

Start with: docker-compose up

MCP Inspector Deep Dive

The MCP Inspector is an essential tool for testing, debugging, and understanding your MCP server.

Installing MCP Inspector

Option 1: Use with npx (recommended for occasional use)

npx @modelcontextprotocol/inspector <command>

Option 2: Global installation

npm install -g @modelcontextprotocol/inspector
mcp-inspector <command>

Basic Inspector Usage

Testing Docker-based Server

npx @modelcontextprotocol/inspector docker run --rm -i \
  -v ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro \
  -v ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro \
  ghcr.io/evergreen-ci/evergreen-mcp-server:latest

Testing Local Installation

# From the project directory
npx @modelcontextprotocol/inspector .venv/bin/evergreen-mcp-server

# With project configuration
npx @modelcontextprotocol/inspector .venv/bin/evergreen-mcp-server --project-id mms

Inspector Interface Walkthrough

When you start the inspector, it opens a web interface (typically at http://localhost:6274).

1. Connection Status Panel

Top-left corner shows:

✅ Connected: Server is running and responding
🔄 Connecting: Inspector is starting the server
❌ Error: Connection failed (check logs)

2. Server Info Tab

Shows:

Server name and version
Available capabilities
Server metadata
Connection details

3. Tools Tab

This is where you test tool calls.

Interface elements:

Tool Selector: Dropdown of available tools
Parameters Panel: JSON editor for tool arguments
Call Tool Button: Execute the tool call
Response Panel: Shows the result

Example workflow:

Select list_user_recent_patches_evergreen

Edit parameters:

{
  "limit": 5,
  "project_id": "mms"
}

Click "Call Tool"
View response in the panel below
Copy patch IDs for next calls

4. Resources Tab

Browse available MCP resources:

List all resources
View resource URIs
Read resource contents
Test resource access

5. Prompts Tab

If the server exposes prompt templates, you can:

List available prompts
View prompt templates
Test prompt execution

6. Logs Panel

Bottom panel shows real-time logs:

Server stdout/stderr
Request/response messages
Error traces
Debug information

Log filtering:

Click icons to filter by severity
Search logs with Cmd+F
Copy logs for debugging

Advanced Inspector Workflows

Workflow 1: Complete Failure Investigation

Simulate the AI assistant's workflow manually:

# Start inspector
npx @modelcontextprotocol/inspector .venv/bin/evergreen-mcp-server

List patches (Tools tab):

{
  "tool": "list_user_recent_patches_evergreen",
  "arguments": { "limit": 10 }
}

Copy a patch_id from the response

Get failed jobs:

{
  "tool": "get_patch_failed_jobs_evergreen",
  "arguments": { "patch_id": "<copied_id>" }
}

Copy a task_id from the failed_tasks array

Get test results:

{
  "tool": "get_task_test_results_evergreen",
  "arguments": { "task_id": "<copied_task_id>", "failed_only": true }
}

Get logs:

{
  "tool": "get_task_logs_evergreen",
  "arguments": { "task_id": "<copied_task_id>", "filter_errors": true }
}

Workflow 2: Performance Testing

Test tool response times and data volume:

Start inspector with logs visible
Call list_user_recent_patches_evergreen with limit: 50
Note response time in logs
Check data size in response panel
Test with different limits to find optimal values

Workflow 3: Error Reproduction

If users report issues:

Start inspector with same configuration as user
Reproduce the exact tool calls
Check logs for error messages
Verify authentication status
Test with different parameters to isolate the issue

Debugging with Inspector

Authentication Issues

Symptoms:

401 errors in logs
"Unauthorized" in responses

Debug steps:

Check "Logs" panel for auth errors
Verify credential files are mounted (Docker) or exist (local)
Test with: list_user_recent_patches_evergreen with limit: 1
Check response for user identification

Tool Parameter Issues

Symptoms:

Tool calls fail with validation errors

Debug steps:

Use the Inspector's parameter editor
Check required vs optional parameters
Verify parameter types (string vs int vs array)
Look at example responses to understand expected formats

Network/API Issues

Symptoms:

Timeouts
Partial responses

Debug steps:

Check logs for GraphQL errors
Monitor response times
Test with smaller data requests
Verify Evergreen API is accessible

Inspector Tips and Tricks

Keyboard shortcuts:

Cmd/Ctrl + F: Search logs
Cmd/Ctrl + K: Clear logs
Cmd/Ctrl + E: Focus parameter editor

JSON editing:

Use the built-in JSON editor for syntax highlighting
Format JSON with Cmd+Shift+F
Validate before calling

Saving test cases:

Copy successful tool calls for documentation
Save parameter sets for regression testing
Export responses for test fixtures

IDE Integration (Detailed)

Comprehensive guides for integrating the Evergreen MCP server with various IDEs and AI coding assistants.

Cursor IDE (Comprehensive)

Setup locations:

Workspace-specific: .cursor/mcp.json in your project root
Global: Settings → Features → MCP

Using uv (recommended):

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ]
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

With automatic project detection (Docker):

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "-v", "${workspaceFolder}:${workspaceFolder}:ro",
        "-e", "WORKSPACE_PATH=${workspaceFolder}",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "evergreen": {
      "command": "/Users/yourname/evergreen-mcp-server/.venv/bin/evergreen-mcp-server",
      "args": ["--workspace-dir", "${workspaceFolder}"]
    }
  }
}

Testing in Cursor:

Save .cursor/mcp.json
Reload window: Cmd+Shift+P → "Developer: Reload Window"
Open MCP panel: Cmd+Shift+P → "MCP: Show Panel"
Verify "evergreen" server shows ✓ Connected
Test by asking: "Show my recent Evergreen patches"

Cursor-specific tips:

Cursor automatically injects workspace context
Use ${workspaceFolder} for workspace-relative paths
Cursor shows MCP status in the status bar
Click the MCP icon to see connected servers

Claude Desktop (Comprehensive)

Configuration file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Using uv (recommended):

{
  "mcpServers": {
    "evergreen": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/evergreen-ci/evergreen-mcp-server",
        "evergreen-mcp-server"
      ]
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ],
      "env": {
        "EVERGREEN_PROJECT": "mongodb-mongo-master"
      }
    }
  },
  "globalShortcut": "Ctrl+Space"
}

Multiple servers example:

{
  "mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "...", "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    }
  }
}

Setup checklist:

✅ Create/edit config file
✅ Validate JSON syntax
✅ Quit Claude Desktop completely (not just close window)
✅ Verify Docker is running: docker ps
✅ Start Claude Desktop
✅ Look for 🔌 icon (bottom-right)
✅ Click 🔌 to verify "evergreen" is connected
✅ Test with a query

Troubleshooting Claude Desktop:

Problem: No 🔌 icon appears

Verify JSON syntax (use jsonlint or online validator)
Check file location is correct
Ensure file is named exactly claude_desktop_config.json

Problem: Server shows as disconnected

Check Docker is running: docker ps
Verify credential files exist: ls -la ~/.evergreen.yml
Check Claude logs: Settings → Advanced → View Logs

Problem: Server connects but tools don't work

Test authentication with: evergreen --version
Verify evergreen login was successful
Check token file exists: ls -la ~/.kanopy/token-oidclogin.json

VS Code MCP Extension (Comprehensive)

Prerequisites:

Install VS Code MCP extension from marketplace
Ensure Docker is installed (for Docker method)

Configuration location:

Open Settings (JSON): Cmd+, → Open Settings (JSON)
Or edit .vscode/settings.json in workspace

Docker configuration:

{
  "mcp.servers": {
    "evergreen": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${userHome}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${userHome}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ],
      "env": {}
    }
  }
}

Per-workspace configuration: Create .vscode/settings.json:

{
  "mcp.servers": {
    "evergreen": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/evergreen-mcp-server",
      "args": ["--workspace-dir", "${workspaceFolder}"],
      "env": {
        "EVERGREEN_PROJECT": "mongodb-mongo-master"
      }
    }
  }
}

VS Code variable reference:

${workspaceFolder}: Current workspace root
${userHome}: User's home directory
${env:VAR_NAME}: Environment variable

Testing in VS Code:

Save settings.json
Reload window: Cmd+Shift+P → "Developer: Reload Window"
Open MCP panel (if extension provides one)
Check Output panel → MCP for logs

Augment (Comprehensive)

Augment is an AI coding assistant available for VS Code and JetBrains IDEs.

Augment in VS Code

Configuration in settings.json:

{
  "augment.mcpServers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ],
      "env": {}
    }
  }
}

Using HTTP/SSE transport:

First, start the server:

docker run --rm -p 8000:8000 \
  -e EVERGREEN_MCP_TRANSPORT=sse \
  -e EVERGREEN_MCP_HOST=0.0.0.0 \
  -v ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro \
  -v ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro \
  ghcr.io/evergreen-ci/evergreen-mcp-server:latest

Then configure Augment:

{
  "augment.mcpServers": {
    "evergreen": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Augment in JetBrains IDEs

Configuration:

Open Augment plugin settings
Navigate to MCP Servers section
Add new server configuration:

{
  "evergreen": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
      "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
      "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
    ]
  }
}

Testing Augment integration:

Restart IDE/reload Augment
Open Augment chat
Type: "Can you check my recent Evergreen patches?"
Augment should use the MCP server to fetch the data

GitHub Copilot Chat (Comprehensive)

Note: MCP support in GitHub Copilot is experimental and may require specific Copilot versions.

VS Code configuration:

{
  "github.copilot.chat.mcp": {
    "servers": {
      "evergreen": {
        "command": "docker",
        "args": [
          "run", "--rm", "-i",
          "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
          "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
          "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
        ]
      }
    }
  }
}

Using with Copilot Workspace:

If using Copilot in workspace mode:

{
  "github.copilot.chat.mcp": {
    "servers": {
      "evergreen": {
        "command": "${workspaceFolder}/.venv/bin/evergreen-mcp-server",
        "args": ["--workspace-dir", "${workspaceFolder}"]
      }
    }
  }
}

Windsurf (Comprehensive)

Windsurf is Codeium's agentic IDE.

Configuration location:

Settings → Extensions → MCP Servers

Configuration:

{
  "mcp.servers": {
    "evergreen": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
        "-v", "${HOME}/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
        "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
      ]
    }
  }
}

Other IDEs and Generic Setup

For any IDE that supports MCP, follow this general pattern:

Step 1: Identify MCP configuration location

Check IDE documentation for MCP settings
Usually in settings JSON or dedicated MCP panel

Step 2: Use appropriate configuration format

Docker-based (most portable):

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "<home>/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro",
    "-v", "<home>/.evergreen.yml:/home/evergreen/.evergreen.yml:ro",
    "ghcr.io/evergreen-ci/evergreen-mcp-server:latest"
  ]
}

Local installation:

{
  "command": "/absolute/path/to/.venv/bin/evergreen-mcp-server",
  "args": []
}

Step 3: Test the configuration

Save configuration
Restart IDE or reload settings
Verify server appears in MCP panel (if available)
Test with a simple query

Configuration Troubleshooting Guide

Problem: Server won't start

Checklist:

✅ Docker is running: docker ps
✅ Credentials exist: ls -la ~/.evergreen.yml ~/.kanopy/token-oidclogin.json
✅ Path is absolute (for local installations)
✅ Virtual environment is activated (for local)
✅ JSON syntax is valid

Problem: Server starts but authentication fails

Check:

evergreen login status
Token file permissions
Config file format
Environment variables

Test manually:

# Docker method
docker run --rm -it \
  -v ~/.kanopy/token-oidclogin.json:/home/evergreen/.kanopy/token-oidclogin.json:ro \
  -v ~/.evergreen.yml:/home/evergreen/.evergreen.yml:ro \
  ghcr.io/evergreen-ci/evergreen-mcp-server:latest \
  --help

# Local method
.venv/bin/evergreen-mcp-server --help

Problem: Tools don't appear or aren't working

Debug steps:

Check IDE logs for MCP errors
Use MCP Inspector to verify tool availability
Test tool calls directly with Inspector
Verify project_id is correct

Troubleshooting

"Authentication failed" errors

Re-run evergreen login to refresh your credentials
Verify ~/.evergreen.yml exists and has valid credentials
Check that ~/.kanopy/token-oidclogin.json exists (for OIDC)
Test authentication: evergreen --version

"Project not found" errors

Use get_inferred_project_ids_evergreen to discover available projects
Specify project_id explicitly in your tool calls
Add project mappings to ~/.evergreen.yml
Verify project identifier spelling (case-sensitive)

Docker permission errors

Ensure Docker can read your credential files:

ls -la ~/.evergreen.yml ~/.kanopy/token-oidclogin.json
chmod 600 ~/.evergreen.yml ~/.kanopy/token-oidclogin.json

Token refresh issues

OIDC tokens expire. Re-run evergreen login if you see authentication errors after some time.

MCP Server won't connect

Check if Docker is running: docker ps

Test Docker image manually:

docker run --rm -it ghcr.io/evergreen-ci/evergreen-mcp-server:latest --help

Verify JSON configuration syntax
Check IDE/client logs for error messages

Tools return no data

Verify you have access to the Evergreen project
Check if patches/tasks exist in the specified time range
Test with broader parameters (higher limit, no filters)
Use MCP Inspector to isolate the issue

Development

Project Structure

evergreen-mcp-server/
├── src/evergreen_mcp/
│   ├── server.py                    # Main MCP server
│   ├── mcp_tools.py                 # Tool definitions
│   ├── evergreen_graphql_client.py  # GraphQL client
│   └── evergreen_queries.py         # GraphQL queries
├── tests/
├── Dockerfile
├── pyproject.toml
└── README.md

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest --cov=evergreen_mcp tests/

Code Quality

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint
flake8 src/ tests/

Updating GraphQL Schema

./scripts/fetch_graphql_schema.sh

Contributing

Fork the repository
Create a feature branch
Make your changes with tests
Ensure all tests pass
Submit a pull request

License

This project follows the same license as the main Evergreen project.

Version

Current version: 0.4.2