Deepsource Mcp Server

DeepSource MCP Server

[](https://github.com/sapientpants/deepsource-mcp-server/actions/workflows/main.yml) [](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/) [](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/) [](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/) [](https://www.npmjs.com/package/deepsource-mcp-server) [](https://www.npmjs.com/package/deepsource-mcp-server) [](https://github.com/sapientpants/deepsource-mcp-server/blob/main/LICENSE)

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](#overview)
• [Quick Start](#quick-start)
• [Installation](#installation)
• [Configuration](#configuration)
• [Available Tools](#available-tools)
• [Usage Examples](#usage-examples)
• [Architecture](#architecture)
• [Development](#development)
• [Troubleshooting & FAQ](#troubleshooting--faq)
• [Contributing](#contributing)
• [License](#license)
• [External Resources](#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"
      }
    }
  }
}

1. 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. recentrunissues

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

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------ | | projectKey | string | Yes | The unique identifier for the DeepSource project | | branchName | string | Yes | The branch name | | first | number | No | Number of items to return | | after | string | No | Cursor for forward pagination |

6. dependency_vulnerabilities

Get security vulnerabilities in project dependencies.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------ | | projectKey | string | Yes | The unique identifier for the DeepSource project | | first | number | No | Number of items to return | | after | string | No | Cursor for forward pagination |

Example Response:

{
  "vulnerabilities": [
    {
      "id": "VUL-001",
      "package": "requests",
      "version": "2.25.0",
      "severity": "HIGH",
      "cve": "CVE-2021-12345",
      "description": "Remote code execution vulnerability"
    }
  ],
  "totalCount": 3
}

7. quality_metrics

Get code quality metrics with optional filtering.

| Parameter | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------------------------ | | projectKey | string | Yes | The unique identifier for the DeepSource project | | shortcodeIn | string[] | No | Filter by metric codes (see below) |

Available Metrics:

• LCV - Line Coverage
• BCV - Branch Coverage
• DCV - Documentation Coverage
• DDP - Duplicate Code Percentage
• SCV - Statement Coverage
• TCV - Total Coverage
• CMP - Code Maturity

8. updatemetricthreshold

Update the threshold for a quality metric.

| Parameter | Type | Required | Description | | ----------------- | ------------ | -------- | ------------------------------------------------ | | projectKey | string | Yes | The unique identifier for the DeepSource project | | repositoryId | string | Yes | The GraphQL repository ID | | metricShortcode | string | Yes | The metric shortcode (e.g., "LCV") | | metricKey | string | Yes | The language or context key | | thresholdValue | number\|null | No | New threshold value, or null to remove |

9. updatemetricsetting

Update metric reporting and enforcement settings.

| Parameter | Type | Required | Description | | --------------------- | ------- | -------- | ------------------------------------------------ | | projectKey | string | Yes | The unique identifier for the DeepSource project | | repositoryId | string | Yes | The GraphQL repository ID | | metricShortcode | string | Yes | The metric shortcode | | isReported | boolean | Yes | Whether to report this metric | | isThresholdEnforced | boolean | Yes | Whether to enforce thresholds |

10. compliance_report

Get security compliance reports.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------ | | projectKey | string | Yes | The unique identifier for the DeepSource project | | reportType | string | Yes | Type of report (see below) |

Available Report Types:

• OWASP_TOP_10 - Web application security vulnerabilities
• SANS_TOP_25 - Most dangerous software errors
• MISRA_C - Guidelines for safety-critical C code
• CODE_COVERAGE - Code coverage report
• CODE_HEALTH_TREND - Quality trends over time
• ISSUE_DISTRIBUTION - Issue categorization
• ISSUES_PREVENTED - Prevented issues count
• ISSUES_AUTOFIXED - Auto-fixed issues count

Usage Examples

Monitor Code Quality Trends

Track your project's quality metrics over time:

"Show me the code coverage trend for my main branch"

This combines multiple tools to:

1. Get recent runs for the main branch
2. Retrieve coverage metrics for each run
3. Display the trend

Set Up Quality Gates

Implement quality gates for CI/CD:

"Set up quality gates: 80% line coverage, 0 critical security issues"

This will:

1. Update the line coverage threshold to 80%
2. Configure enforcement for the threshold
3. Check current critical security issues

Investigate Security Vulnerabilities

Comprehensive security analysis:

"Analyze all security vulnerabilities in my project including dependencies"

This performs:

1. Dependency vulnerability scan
2. Code security issue analysis
3. OWASP Top 10 compliance check
4. Prioritized remediation suggestions

Code Review Assistance

Get AI-powered code review insights:

"What are the most critical issues in the recent commits to feature/new-api?"

This will:

1. Find the most recent run on the branch
2. Filter for critical and high severity issues
3. Group by file and issue type
4. Suggest fixes

Team Productivity Metrics

Track team code quality metrics:

"Show me code quality metrics across all our Python projects"

This aggregates:

1. Coverage metrics per project
2. Issue counts by severity
3. Trends over the last month
4. Team performance insights

Architecture

The DeepSource MCP Server uses modern TypeScript patterns for maintainability and type safety.

Key Components

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude/AI      │────▶│   MCP Server     │────▶│  DeepSource API │
│  Assistant      │◀────│  (TypeScript)    │◀────│   (GraphQL)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘

1. MCP Server Integration (src/index.ts)

• Registers and implements tool handlers
• Manages MCP protocol communication
• Handles errors and logging

1. DeepSource Client (src/deepsource.ts)

• GraphQL API communication
• Authentication and retry logic
• Response parsing and validation

1. Type System (src/types/)

• Branded types for type safety
• Discriminated unions for state management
• Zod schemas for runtime validation

Type Safety Features

Branded Types

// Prevent mixing different ID types
type ProjectKey = string & { readonly __brand: 'ProjectKey' };
type RunId

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sapientpants](https://github.com/sapientpants)
- **Source:** [sapientpants/deepsource-mcp-server](https://github.com/sapientpants/deepsource-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.