DeepSource

DeepSource MCP Server

A Model Context Protocol (MCP) server that integrates with DeepSource to provide AI assistants with access to code quality metrics, issues, and analysis results.

Table of Contents

• Overview
• Quick Start
• Installation
• Configuration
• Available Tools
• Usage Examples
• Architecture
• Development
• Troubleshooting & FAQ
• Contributing
• License
• External Resources

Overview

The DeepSource MCP Server enables AI assistants like Claude to interact with DeepSource's code quality analysis capabilities through the Model Context Protocol. This integration allows AI assistants to:

• Retrieve code metrics and analysis results
• Access and filter issues by analyzer, path, or tags
• Check quality status and set thresholds
• Analyze project quality over time
• Access security compliance reports (OWASP, SANS, MISRA-C)
• Monitor dependency vulnerabilities
• Manage quality gates and thresholds

Quick Start

1. Get Your DeepSource API Key

1. Log in to your DeepSource account
2. Navigate to Settings → API Access
3. Click Generate New Token
4. Copy your API key and keep it secure

2. Install in Claude Desktop

1. Open Claude Desktop
2. Go to Settings → Developer → Edit Config
3. Add this configuration to the mcpServers section:

{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}

4. Restart Claude Desktop

3. Test Your Connection

Ask Claude: "What DeepSource projects do I have access to?"

If configured correctly, Claude will list your available projects.

Installation

NPX (Recommended)

The simplest way to use the DeepSource MCP Server:

{
  "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

For containerized environments:

{
  "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

For development or customization:

{
  "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

Environment Variables

Variable	Required	Default	Description
DEEPSOURCE_API_KEY	Yes	-	Your DeepSource API key for authentication
LOG_FILE	No	-	Path to log file. If not set, no logs are written
LOG_LEVEL	No	DEBUG	Minimum log level: DEBUG, INFO, WARN, ERROR
RETRY_MAX_ATTEMPTS	No	3	Maximum number of retry attempts for failed requests
RETRY_BASE_DELAY_MS	No	1000	Base delay in milliseconds for exponential backoff
RETRY_MAX_DELAY_MS	No	30000	Maximum delay in milliseconds between retries
RETRY_BUDGET_PER_MINUTE	No	10	Maximum retries allowed per minute across all operations
CIRCUIT_BREAKER_THRESHOLD	No	5	Number of failures before circuit breaker opens
CIRCUIT_BREAKER_TIMEOUT_MS	No	30000	Time in milliseconds before circuit breaker attempts recovery

Performance Considerations

• Pagination: Use appropriate page sizes (10-50 items) to balance response time and data completeness
• Automatic Retry: The server implements intelligent retry logic with:
  • Exponential backoff with jitter to prevent thundering herd
  • Circuit breaker pattern to prevent cascade failures
  • Retry budget to limit resource consumption
  • Respect for Retry-After headers from the API
• Rate Limits: Rate-limited requests (429) are automatically retried with appropriate delays
• Fault Tolerance: Transient failures (network, 502, 503, 504) are handled gracefully
• Caching: Results are not cached. Consider implementing caching for frequently accessed data

Available Tools

1. projects

List all available DeepSource projects.

Parameters: None

Example Response:

[
  {
    "key": "https://api-key@app.deepsource.com",
    "name": "my-python-project"
  }
]

2. project_issues

Get issues from a DeepSource project with filtering and pagination.

Parameter	Type	Required	Description
projectKey	string	Yes	The unique identifier for the DeepSource project
first	number	No	Number of items to return (forward pagination)
after	string	No	Cursor for forward pagination
last	number	No	Number of items to return (backward pagination)
before	string	No	Cursor for backward pagination
path	string	No	Filter issues by file path
analyzerIn	string[]	No	Filter by analyzers (e.g., ["python", "javascript"])
tags	string[]	No	Filter by issue tags

Example Response:

{
  "issues": [
    {
      "id": "T2NjdXJyZW5jZTpnZHlqdnlxZ2E=",
      "title": "Avoid using hardcoded credentials",
      "shortcode": "PY-D100",
      "category": "SECURITY",
      "severity": "CRITICAL",
      "file_path": "src/config.py",
      "line_number": 42
    }
  ],
  "totalCount": 15,
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "YXJyYXljb25uZWN0aW9uOjQ="
  }
}

3. runs

List analysis runs for a project with filtering.

Parameter	Type	Required	Description
projectKey	string	Yes	The unique identifier for the DeepSource project
first	number	No	Number of items to return (forward pagination)
after	string	No	Cursor for forward pagination
last	number	No	Number of items to return (backward pagination)
before	string	No	Cursor for backward pagination
analyzerIn	string[]	No	Filter by analyzers

4. run

Get details of a specific analysis run.

Parameter	Type	Required	Description
projectKey	string	Yes	The unique identifier for the DeepSource project
runIdentifier	string	Yes	The runUid (UUID) or commitOid (commit hash)
isCommitOid	boolean	No	Whether runIdentifier is a commit hash (default: false)

5. recent_run_issues

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

Parameter	Type	Required	Description

---

README truncated. View full README on GitHub.