DeepSource

You can run a Model Context Protocol (MCP) server that connects Claude-like AI assistants to DeepSource's code quality metrics, issues, and analysis results. This server lets AI agents query projects, analyze trends, track quality gates, and surface security and vulnerability information to improve code quality and reliability.

How to use

You interact with the server through your MCP client by selecting the deepsource MCP server configuration you started. The server exposes tools to list projects, fetch issues with filters, inspect analysis runs, review quality metrics, and retrieve security reports. Use natural language prompts to ask for trends, filters, or specific vulnerabilities, and the AI assistant will translate your request into the appropriate data retrieval using the available tools.

How to install

Prerequisites you need before installing the MCP server on your machine are Node.js version 22.19.0 or higher and pnpm version 10.15.1 or higher. Docker is optional if you prefer containerized execution.

Choose one of the supported installation modes and follow the steps.

NPX (Recommended)

{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "INFO",
        "RETRY_MAX_ATTEMPTS": "3",
        "RETRY_BASE_DELAY_MS": "1000",
        "RETRY_MAX_DELAY_MS": "30000",
        "RETRY_BUDGET_PER_MINUTE": "10",
        "CIRCUIT_BREAKER_THRESHOLD": "5",
        "CIRCUIT_BREAKER_TIMEOUT_MS": "30000"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "deepsource": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DEEPSOURCE_API_KEY",
        "-e",
        "LOG_FILE=/tmp/deepsource-mcp.log",
        "-v",
        "/tmp:/tmp",
        "sapientpants/deepsource-mcp-server"
      ],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}

Local Development

{
  "mcpServers": {
    "deepsource": {
      "command": "node",
      "args": ["/path/to/deepsource-mcp-server/dist/index.js"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Configuration and environment

Set up environment variables to control access and behavior. The key required variable is DEEPSOURCE_API_KEY. Optional variables control logging, retry behavior, and circuit breaking. You can configure them in the MCP server configuration or environment as shown in the installation blocks.

Available tools overview

The MCP server provides a collection of endpoints to interact with DeepSource data. You can list projects, fetch issues with filters, inspect analysis runs, retrieve vulnerability data, access quality metrics, and obtain security compliance reports.

Usage examples

Monitor code quality trends, set up quality gates for CI/CD, investigate security vulnerabilities, or request AI-powered code review insights by asking natural language questions. For example, you can ask for the latest quality metrics on a project, or request a security issue breakdown by severity.

Architecture

The MCP server architecture pairs an AI assistant with a TypeScript MCP server that communicates with the DeepSource GraphQL API. It handles MCP protocol messaging, error handling, and logging while providing a typed and validated data flow.

Development

You can build and test locally by installing dependencies, building the TypeScript code, and running tests. The project uses pnpm for package management and supports a development inspector for debugging MCP interactions.

Troubleshooting & FAQ

If you encounter authentication errors, verify your DeepSource API key and permissions. If no projects are found, ensure the key has access to at least one project. Rate limits are retried automatically, but you can slow down request frequency if needed. Cursors for pagination expire, so start anew if you see an invalid cursor error.

Contributing

Contributions are welcome. Follow conventional commit messages and run the full test suite to verify changes.

License

MIT - see LICENSE for details.

Notes

This MCP server is designed to integrate Claude-like assistants with DeepSource data to enhance code quality analysis, security insights, and tooling for development teams.

Available tools

projects

List all available DeepSource projects.

project_issues

Get issues from a DeepSource project with filtering and pagination.

runs

List analysis runs for a project with filtering.

run

Get details of a specific analysis run.

recent_run_issues

Get issues from the most recent analysis run on a branch.

dependency_vulnerabilities

Get security vulnerabilities in project dependencies.

quality_metrics

Get code quality metrics with optional filtering.

update_metric_threshold

Update the threshold for a quality metric.

update_metric_setting

Update metric reporting and enforcement settings.

compliance_report

Get security compliance reports.