# Deepsource Mcp Server

> Model Context Protocol (MCP) server for DeepSource

- **Type:** MCP server
- **Install:** `agentstack add mcp-sapientpants-deepsource-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sapientpants](https://agentstack.voostack.com/s/sapientpants)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sapientpants](https://github.com/sapientpants)
- **Source:** https://github.com/sapientpants/deepsource-mcp-server

## Install

```sh
agentstack add mcp-sapientpants-deepsource-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://app.deepsource.com)
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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**:

```json
[
  {
    "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**:

```json
{
  "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                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `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**:

```json
{
  "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. update_metric_threshold

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. update_metric_setting

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

2. **DeepSource Client** (`src/deepsource.ts`)
   - GraphQL API communication
   - Authentication and retry logic
   - Response parsing and validation

3. **Type System** (`src/types/`)
   - Branded types for type safety
   - Discriminated unions for state management
   - Zod schemas for runtime validation

### Type Safety Features

#### Branded Types

```typescript
// 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sapientpants-deepsource-mcp-server
- Seller: https://agentstack.voostack.com/s/sapientpants
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.