sonar-mcp-server

# Sonar MCP Server

[![CI](https://github.com/igorolv/sonar-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/igorolv/sonar-mcp-server/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/igorolv/sonar-mcp-server?include_prereleases)](https://github.com/igorolv/sonar-mcp-server/releases/latest)
[![License](https://img.shields.io/github/license/igorolv/sonar-mcp-server)](LICENSE)
[![Java 25](https://img.shields.io/badge/Java-25%2B-blue?logo=openjdk)](https://adoptium.net/)
[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io/)
[![Glama score](https://glama.ai/mcp/servers/igorolv/sonar-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/igorolv/sonar-mcp-server)

A local MCP server providing read-only access to a SonarQube Community Build (26.4+) instance via its web-api.
It lets AI agents (Claude Code, Cursor, VS Code Copilot, etc.) fetch a project's issue list, the files and locations where they occur, rule descriptions, source-code snippets around issues, and Security Hotspots.

Typical scenario: "find and fix Sonar issues in such-and-such project" — the LLM calls `listIssues`, optionally `getRule` and `getIssueSnippets`, and edits files locally.

## Why this server

There is an official SonarSource MCP server, but it targets SonarQube **10+** (and SonarCloud) and assumes a cloud-style deployment. This server is built for self-hosted **SonarQube Community Build 26.4+** installations that expose the classic `/api/` web-api. It supports both Standard Experience and MQR mode, handling per-software-quality impacts when the instance runs in MQR mode.

It is also intentionally narrower in scope:

- **Read-only by design.** The server never creates, updates, or deletes anything in SonarQube — no marking issues as false-positive, no editing comments, no admin endpoints. The token's write permissions in SonarQube are irrelevant because the server never calls those endpoints.
- **Curated tool set.** Instead of mirroring the SonarQube API surface, the server exposes a small, focused set of tools (13 in total) chosen for a single workflow: *let an AI agent read Sonar's findings and fix the code based on them*. Listing components, issues and hotspots, drilling into a single finding, fetching the rule explanation, and pulling the source-code snippet around the location — and that's it. Anything outside this "diagnose -> fix the code locally" loop is deliberately left out to keep the tool list small and the agent's choices unambiguous.

In short: a focused, read-only bridge from a self-hosted SonarQube Community Build to an AI coding agent.

## Quick start

1. Install JDK 25+.
2. Download `sonar-mcp-server.jar` from the [latest release](https://github.com/igorolv/sonar-mcp-server/releases/latest),
   or build it yourself: `./gradlew bootJar` (see [Build](#build)). A [Docker image](#docker) is
   published as well.
3. Get your SonarQube URL and user token (see [Configuration](#configuration)).
4. Add the JAR to your client's MCP configuration (see [Connecting to an AI client](#connecting-to-an-ai-client)).

For Claude Code that is one command:

```bash
claude mcp add --scope user -e SONAR_URL=https://sonar.example.com -e SONAR_TOKEN=your_token -- sonar java -jar /path/to/sonar-mcp-server.jar
```

## Architecture

The server only supports the `stdio` transport.

```
┌─────────────┐     stdio      ┌──────────────────┐    web-api     ┌──────────┐
│  AI agent   │ <------------> │  sonar-mcp-      │ -------------> │ SonarQube│
│ (Claude Code│   stdin/stdout │  server (Java)   │  HTTP + Bearer  │  CB 26.4+│
│  Cursor...) │                │                  │  auth (token)   │          │
└─────────────┘                └──────────────────┘                └──────────┘
```

The AI client spawns the server as a child process; communication uses the MCP protocol over stdin/stdout.
The server does not open any HTTP port and accepts no incoming connections.

## Tools

The server exports **13 read-only MCP tools**.

### Projects

| Tool | Description |
|---|---|
| `listProjects` | List of SonarQube projects. Parameters: `query` (name substring), `limit`, `offset`. Returns `key`, `name`, `qualifier`. |
| `listComponents` | Search/browse components inside a project using Sonar's component tree. Parameters: `projectKey`, `query`, `qualifiers`, `branch` / `pullRequest`, `limit`, `offset`. Returns opaque component `key` values plus `path`, `qualifier`, name, language, and project. Use returned `key` values unchanged as `listIssues.componentKeys`; do not pass Java package names directly as component keys. |
| `getProject` | Project overview: header info (name, qualifier, visibility, description, version, last analysis date), quality gate status with failed conditions, and curated metrics (ncloc, bugs, vulnerabilities, security hotspots, code smells, coverage, duplicated lines density, technical debt in minutes, alert status). Parameters: `projectKey`, `branch` (opt.), `pullRequest` (opt.). |
| `listProjectBranches` | List of branches analysed for the project. Each entry: `name`, `isMain`, `type` (LONG/SHORT/BRANCH), `excludedFromPurge`, `analysisDate`, `qualityGateStatus`, plus bugs/vulnerabilities/codeSmells counts. No pagination — Sonar returns all branches at once. |
| `listProjectPullRequests` | List of PR analyses for the project. Each entry: PR `key` (use as `pullRequest=` elsewhere), `title`, `branch` (head), `base`, `url`, `analysisDate`, `qualityGateStatus`, plus bugs/vulnerabilities/codeSmells counts. Empty list if the Sonar install has no DevOps integration. |

### Issues

| Tool | Description |
|---|---|
| `listIssues` | Flat list of issues for a project. Parameters: `projectKey` (required unless defaulted), `componentPathPrefix` (opt.) — a single subtree-or-file filter relative to the Sonar project root (e.g. `bc-doc/src/main/java/ru/foo` or `bc-doc/src/main/java/ru/foo/Bar.java`); convert Java/Kotlin package dots to slashes; honours directory boundaries (`bc-doc/src` does not match `bc-doc/srcExtra`). Plus `severities`, `types`, `statuses`, `rules`, `branch` / `pullRequest` (mutually exclusive), `resolved`, `limit`, `offset`. By default returns only open issues (`resolved=false`, statuses OPEN/CONFIRMED/REOPENED). Each item contains the rule, severity, type, status, file path, line, primary textRange, and secondary flows for cross-file rules. When `componentPathPrefix` is used, the server scans the project and filters client-side; the scan is capped (default 10000 issues) — if the cap is hit, `pathPrefixTruncated=true` in the response. |
| `getIssue` | Details of a single issue by key plus its change history (`changelog`). Accepts optional `branch` / `pullRequest`. |
| `getIssueSnippets` | Source-code snippets around all issue locations (primary plus flows for cross-file rules). For each location: `componentPath`, language, and an array of source lines with SCM info. Useful when the repository isn't available locally or you need to see exactly the file version Sonar analyzed. Accepts optional `branch` / `pullRequest` — important when the issue lives on a non-main ref whose files differ from main. |
| `getProjectIssuesSummary` | Aggregated summary of open issues in a project: total plus breakdowns by severity, type, status, rule, tag, and SCM author. Parameters mirror `listIssues` (incl. `componentPathPrefix`) except pagination. |
| `getProjectIssuesBreakdown` | Multi-module aggregation of issues by logical module and rule. Module is derived from the first `componentPath` segment. Parameters mirror `getProjectIssuesSummary`. |

### Rules

| Tool | Description |
|---|---|
| `getRule` | Details of a Sonar rule by key (e.g. `java:S1234`): title, severity, type, language, tags, description sections (introduction, root cause, how to fix, resources). Backed by an in-memory cache — repeated calls are free. |

### Security Hotspots

| Tool | Description |
|---|---|
| `listHotspots` | List of Security Hotspots for a project. Hotspots are a separate category from issues, marking spots that require manual security review. By default Sonar returns hotspots in status `TO_REVIEW`. Parameters: `projectKey`, `componentPathPrefix` (opt.) — same prefix semantics as on `listIssues`, `status` (opt.), `branch` / `pullRequest` (opt., mutually exclusive), `limit`, `offset`. Subject to the same client-side scan cap (`pathPrefixTruncated` flag in the response). |
| `getHotspot` | Security Hotspot details: full rule description (risk, vulnerability, fix recommendations), primary textRange, secondary flows, changelog. Hotspot keys are globally unique, so no `branch`/`pullRequest` parameter is needed. |

All tools are **read-only** — no data in SonarQube is modified.

### Working with branches and pull requests

Sonar analyses a *branch* and a *pull request* as two distinct, mutually exclusive scopes. The Sonar web-api accepts either `branch=` or `pullRequest=` on a single request, never both.

- **`branch`** — long-lived branches (main, develop, feature/...). Resolved as: explicit `branch` argument → `SONAR_DEFAULT_BRANCH` → none (Sonar uses the project's main branch).
- **`pullRequest`** — the Sonar PR key, usually the PR/MR number. Independent from branch analyses; PR analyses often contain the most relevant findings for in-flight work. Pull request keys never fall back to a server-level default — pass them explicitly.

Passing both `branch` and `pullRequest` to the same tool call is an error. Use `listProjectBranches` / `listProjectPullRequests` to discover available refs.

> **Branch scoping is load-bearing.** Each Sonar branch is a separate analysis: open-issue counts on `main` and on a feature branch can differ a lot, because the feature branch may have new fixes (or new code) that have not been merged. If the agent silently omits `branch=`, it reads from `main` (or `SONAR_DEFAULT_BRANCH`) and may miss work already done on a feature branch — or worse, fix the same prob