SonarQube MCP Server

A read-only Model Context Protocol (MCP) server that gives AI assistants structured access to SonarQube — issues, metrics, rules, and projects.

Features

• 6 read-only tools covering the full SonarQube quality workflow

• Safe by design — no mutations, every tool returns a consistent {"ok": ...} envelope

• Input validation before any API call (severities, types, statuses)

• Structured errors with machine-readable error_code fields

• Works with SonarQube Community, Developer, and Enterprise editions

Requirements

• Python 3.10+

• A running SonarQube instance

• A SonarQube user token (squ_...)

Installation

pip install sonarqube-mcp-server

Or install from source:

git clone <repo>
cd sonarqube-mcp
pip install -e .

Quick Start

SONARQUBE_URL=http://localhost:9000 \
SONARQUBE_TOKEN=squ_xxxxxxxxxxxx \
sonarqube-mcp-server

Or with python -m:

python -m sonarqube_mcp

Configuration

Environment Variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

Generating a Token

In SonarQube: My Account → Security → Generate Tokens. A user token (squ_...) with Browse permission on the target projects is sufficient for all read-only operations.

MCP Client Integration

Claude Code

Add to your Claude Code MCP settings (~/.claude/claude_code_config.json):

{
  "mcpServers": {
    "sonarqube": {
      "command": "sonarqube-mcp-server",
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_xxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sonarqube": {
      "command": "sonarqube-mcp-server",
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_xxxxxxxxxxxx"
      }
    }
  }
}

Tools

All tools are read-only (readOnlyHint: true, destructiveHint: false).

check_status

Verify connectivity and retrieve server version.

{}

Response:

{
  "ok": true,
  "server_url": "http://localhost:9000",
  "status": "UP",
  "version": "10.4.1"
}

list_projects

List or search SonarQube projects with pagination.

Response:

{
  "ok": true,
  "total": 42,
  "page": 1,
  "page_size": 20,
  "projects": [
    {"key": "my-app", "name": "My Application", "qualifier": "TRK"}
  ]
}

search_issues

Search issues across all projects or scoped to one project, with rich filtering.

Example — find all open blockers in a project:

{
  "project_key": "my-app",
  "severities": "BLOCKER,CRITICAL",
  "statuses": "OPEN"
}

get_issue

Get full detail for a single issue by key, including text range, effort, assignee, comments, and data-flow information.

get_project_metrics

Retrieve the quality dashboard for a project. Returns a standard set of metrics by default, or a custom selection.

Default metrics: bugs, vulnerabilities, code_smells, security_hotspots, coverage, duplicated_lines_density, ncloc, sqale_index, reliability_rating, security_rating, sqale_rating, alert_status, quality_gate_details

Response:

{
  "ok": true,
  "project_key": "my-app",
  "project_name": "My Application",
  "metrics": {
    "bugs": "3",
    "coverage": "78.4",
    "alert_status": "OK"
  }
}

get_rule

Retrieve the description and metadata for a SonarQube rule.

Error Handling

All tools return a consistent envelope. On failure:

{
  "ok": false,
  "error_code": "auth_error",
  "message": "Authentication failed. Check SONARQUBE_TOKEN.",
  "details": {}
}

Development

Setup

pip install -e ".[dev]"

Running Tests

pytest

Project Layout

src/sonarqube_mcp/
├── server.py             # FastMCP server, tool definitions, main()
├── sonarqube_client.py   # httpx.Client wrapper for SonarQube REST API
├── settings.py           # Frozen dataclass + env var loading
├── errors.py             # SonarQubeError + error_response()
├── __main__.py           # python -m sonarqube_mcp entrypoint
└── __init__.py

tests/
├── conftest.py
├── test_server.py
├── test_client.py
├── test_settings.py
└── test_errors.py

Architecture Notes

• create_server() is a factory that captures settings and client in closure scope — makes unit testing straightforward by injecting a pre-built SonarQubeSettings.

• @_safe_tool wraps every tool so it never raises — exceptions are caught and returned as structured error envelopes.

• _clamp() keeps page_size within SonarQube's supported API limits (1–500).

• Settings use a frozen=True dataclass — immutable after load, safe to share across tool closures.

License

MIT