SonarQube Community Build MCP server
Commit Sep 18, 2026Provides AI agents with read-only access to SonarQube Community Build issues, security hotspots, rule descriptions, and source-code snippets.
Also known as igorolv/sonar-mcp-server, sonar-mcp-server
- Stars
- 1
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Sep 18, 2026
- License
- MIT
What is SonarQube Community Build MCP?
SonarQube Community Build provides AI agents with read-only access to SonarQube Community Build issues, security hotspots, rule descriptions, and source-code snippets. It exposes 13 tools, such as getHotspot, listHotspots, getIssue.
Summary generated from the project's README
About SonarQube Community Build MCP server
Developers using self-hosted SonarQube Community Build 26.4+ can connect their AI coding agents to their static analysis findings. This local MCP server acts as a read-only bridge, allowing tools like Claude Code, Cursor, or VS Code Copilot to inspect code quality data without modifying the SonarQube instance. It uses the stdio transport to communicate with clients and requires a SonarQube URL and user token for authentication.
The server provides a curated set of 13 tools specifically designed to help an agent diagnose and fix code. Instead of exposing the entire API, it focuses on essential actions like listing projects, fetching issue lists, retrieving rule descriptions, and pulling source-code snippets around specific vulnerabilities. It also supports inspecting security hotspots and navigating different branches or pull requests to ensure the agent is looking at the correct version of the code.
What you can do with it
- 1Fixing SonarQube issuesAn AI agent can identify specific code smells or bugs and apply fixes directly to your local files.
- 2Analyzing security hotspotsYou can task an agent with reviewing manual security review points identified by SonarQube.
- 3Reviewing pull request findingsAn agent can examine analysis results specifically for an active pull request to validate in-flight work.
Written from the project's README. Every use case is checked against a quote from it.
How to install SonarQube Community Build MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SonarQube Community Build MCP in Claude Code
$ claude mcp add --env 'SONAR_TOKEN=<YOUR_SONAR_TOKEN>' --env 'SONAR_URL=<SONAR_URL>' sonar-mcp-server -- docker run -i --rm ghcr.io/igorolv/sonar-mcp-server:0.1.0Install SonarQube Community Build MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sonar-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/sonar-mcp-server:0.1.0"
],
"env": {
"SONAR_TOKEN": "<YOUR_SONAR_TOKEN>",
"SONAR_URL": "<SONAR_URL>"
}
}
}
}Install SonarQube Community Build MCP in VS Code
.vscode/mcp.json
{
"servers": {
"sonar-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/sonar-mcp-server:0.1.0"
],
"env": {
"SONAR_TOKEN": "<YOUR_SONAR_TOKEN>",
"SONAR_URL": "<SONAR_URL>"
}
}
}
}Install SonarQube Community Build MCP in VS Code CLI
$ code --add-mcp '{"name":"sonar-mcp-server","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/igorolv/sonar-mcp-server:0.1.0"],"env":{"SONAR_TOKEN":"<YOUR_SONAR_TOKEN>","SONAR_URL":"<SONAR_URL>"}}'Install SonarQube Community Build MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"sonar-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/sonar-mcp-server:0.1.0"
],
"env": {
"SONAR_TOKEN": "<YOUR_SONAR_TOKEN>",
"SONAR_URL": "<SONAR_URL>"
}
}
}
}Install SonarQube Community Build MCP in Codex
$ codex mcp add sonar-mcp-server --env 'SONAR_TOKEN=<YOUR_SONAR_TOKEN>' --env 'SONAR_URL=<SONAR_URL>' -- docker run -i --rm ghcr.io/igorolv/sonar-mcp-server:0.1.0Install SonarQube Community Build MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.sonar-mcp-server] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/igorolv/sonar-mcp-server:0.1.0"] [mcp_servers.sonar-mcp-server.env] SONAR_TOKEN = "<YOUR_SONAR_TOKEN>" SONAR_URL = "<SONAR_URL>"
Install SonarQube Community Build MCP in Gemini CLI
$ gemini mcp add -s user -e 'SONAR_TOKEN=<YOUR_SONAR_TOKEN>' -e 'SONAR_URL=<SONAR_URL>' sonar-mcp-server docker -- run -i --rm ghcr.io/igorolv/sonar-mcp-server:0.1.0Install SonarQube Community Build MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sonar-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/sonar-mcp-server:0.1.0"
],
"env": {
"SONAR_TOKEN": "<YOUR_SONAR_TOKEN>",
"SONAR_URL": "<SONAR_URL>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for ghcr.io/igorolv/sonar-mcp-server:0.1.0 0.1.0 in an isolated container with no network and no keys. It answered and listed 13 tools. It ran on an x86 (amd64) build; ARM machines may need emulation.
SonarQube Community Build MCP tools 13
Read from the server with tools/listgetHotspotRead-onlyGet one Security Hotspot. Returns review details, rule guidance, locations, flows, and changelog.
listHotspotsRead-onlyList project Security Hotspots that need human review. Defaults to `TO_REVIEW`; supports path and ref filters. Returns rule/category, vulnerability probability, message, and file location. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`.
getIssueRead-onlyGet one issue by key. Returns full issue details and changelog, including status and assignment history. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`.
getIssueSnippetsRead-onlyGet Sonar-analysed source snippets for all issue locations, including cross-file flows. Returns component path, language, code lines, and SCM metadata. Use when local source is unavailable or may differ from the analysed ref. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`.
getProjectIssuesBreakdownRead-onlyCount project issues by logical module and rule; intended for multi-module projects. A module is the first `componentPath` segment. Returns totals, module/rule facets, and per-module severity/type summaries. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`. If `branchAdvisory` is present, choose the branch matching the user's ref and retry explicitly.
getProjectIssuesSummaryRead-onlyCount project issues and group them by severity, type, status, rule, tag, and SCM author. Returns the total and facet counts; use before listing details. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`. If `branchAdvisory` is present, choose the branch matching the user's ref and retry explicitly.
listIssuesRead-onlyList project issues with optional severity, type, status, rule, path, and ref filters. Returns rule, severity, type, status, message, file location/text range, and cross-file flows. Defaults to open issues. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`. If `branchAdvisory` is present, choose the branch matching the user's ref and retry explicitly.
getProjectRead-onlyGet one project analysis. Returns project metadata, quality gate failures, and metrics for size, findings, coverage, duplication, and technical debt. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`.
listComponentsRead-onlyBrowse or search a project's analysed component tree. Use returned `path` values as `componentPathPrefix`; Sonar paths may differ from repository paths. Returns component key, path, name, qualifier, and language. Use `qualifiers=DIR` to discover directories. Scope explicitly: omitting both `branch` and `pullRequest` uses the configured default (usually main). For non-main or PR work, pass the matching ref explicitly; discover it with `listProjectBranches` / `listProjectPullRequests`.
listProjectBranchesRead-onlyList analysed project branches. Returns name, main/type flags, analysis date, quality gate, and issue counts; use the name as `branch` in other tools.
listProjectPullRequestsRead-onlyList project PR analyses. Returns key, title, source/base branches, URL, analysis date, quality gate, and issue counts; use the key as `pullRequest` in other tools. Returns empty when DevOps integration is unavailable.
listProjectsRead-onlyList projects, optionally filtered by name. Returns key, name, and qualifier; use the key as `projectKey` in other tools.
Show all 13 toolsShow fewer tools
getRuleRead-onlyGet a Sonar rule. Returns title, severity, type, language, tags, and structured explanation and fix sections.
Configuration
SONAR_TOKENRequiredSecretSonarQube user token (My Account -> Security -> Generate Tokens)
SONAR_URLRequiredBase URL of the SonarQube instance, e.g. https://sonar.example.com
JAVA_HOMESONAR_DEFAULT_PROJECT_KEYProject key used when a tool call does not name one
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableigorolv/sonar-mcp-server is public and reachablegithub.com/igorolv/sonar-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-18github.com/igorolv/sonar-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model2 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSonar 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
- Install JDK 25+.
- Download
sonar-mcp-server.jarfrom the latest release, or build it yourself:./gradlew bootJar(see Build). A Docker image is published as well. - Get your SonarQube URL and user token (see Configuration).
- Add the JAR to your client's MCP configuration (see Connecting to an AI client).
For Claude Code that is one command:
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: explicitbranchargument →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
mainand 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 omitsbranch=, it reads frommain(orSONAR_DEFAULT_BRANCH) and may miss work already done on a feature branch — or worse, fix the same problem twice. When the user's local git is onfeature/..., agents should calllistProjectBranchesfirst, find the matching Sonar branch, and pass it explicitly to every issue / summary / breakdown call.As a server-side safety net,
listIssues,getProjectIssuesSummary, andgetProjectIssuesBreakdownattach abranchAdvisoryfield to their response when (1) neitherbranchnorpullRequestwas passed AND (2) the project has other branches analysed in Sonar. The advisory carries the effective (main) branch name and the list of non-main branches sorted by most recent analysisDate. The field is absent otherwise.
Stack
- Java 25, Spring Boot 4.0.0, Spring AI MCP 2.0.0 (stdio transport)
- Jackson 3 (
tools.jackson) for JSON - Gradle 9.3.1 with version catalog (
gradle/libs.versions.toml)
Build
# Point to a JDK 25+ if it's not the default:
export JAVA_HOME="$HOME/.jdks/jdk-25.0.2"
./gradlew build
On Windows: .\gradlew.bat build.
Output: build/libs/sonar-mcp-server.jar
Configuration
The server needs a SonarQube URL and token; the rest is optional.
| Variable | Description |
|---|---|
SONAR_URL |
SonarQube base URL (e.g. http://sonar.example.com) |
SONAR_TOKEN |
SonarQube user token |
SONAR_DEFAULT_PROJECT_KEY |
Default SonarQube project key. When set, listIssues, getProjectIssuesSummary, listHotspots can be called without projectKey. |
SONAR_DEFAULT_BRANCH |
Default Sonar branch. When set, all branch-aware tools (listIssues, getIssue, getIssueSnippets, getProjectIssuesSummary, listHotspots) fall back to this branch when branch is omitted. Without it Sonar uses the project's main branch. |
SONAR_MCP_DATA_DIR |
Local data directory for the server; defaults to ~/.sonar-mcp-server |
SONAR_MCP_PAGINATION_DEFAULT_LIMIT |
Default page limit for list tools; defaults to 50 |
SONAR_MCP_PAGINATION_DEFAULT_OFFSET |
Default offset for list tools; defaults to 0 |
SONAR_MCP_PAGINATION_MAX_LIMIT |
Max page limit (Sonar API itself caps at 500); defaults to 500 |
SONAR_MCP_SNIPPET_MAX_LINES |
Reserved for future per-snippet line cap; currently unused (Sonar picks the window itself). Defaults to 50 |
SONAR_MCP_PATH_FILTER_MAX_SCANNED_ISSUES |
Hard cap on issues/hotspots scanned client-side when componentPathPrefix is set; defaults to 10000. If the cap is hit, the response carries pathPrefixTruncated=true. |
Tool groups
The MCP tools/list manifest is split into four groups, each gated by an environment flag. All groups are on by default, so the out-of-the-box manifest is unchanged. Turn a group off to shrink the manifest — useful for small-context (local) models that would otherwise be flooded with tool and output schemas at session start.
| Variable | Tools in the group |
|---|---|
SONAR_MCP_TOOLS_ISSUE |
listIssues, getIssue, getIssueSnippets, getProjectIssuesSummary, getProjectIssuesBreakdown |
SONAR_MCP_TOOLS_PROJECT |
listProjects, listComponents, getProject, listProjectBranches, listProjectPullRequests |
SONAR_MCP_TOOLS_HOTSPOT |
listHotspots, getHotspot |
SONAR_MCP_TOOLS_RULE |
getRule |
Set a flag to false (e.g. SONAR_MCP_TOOLS_HOTSPOT=false) to drop that group's tools from the manifest.
Getting the SonarQube URL
Open SonarQube in a browser and copy the address from the location bar without the path — only scheme and host.
| In the browser address bar | URL value |
|---|---|
https://sonar.example.com/dashboard?id=... |
https://sonar.example.com |
http://192.168.1.50:9000/projects |
http://192.168.1.50:9000 |
http://10.0.0.5/sonar/projects |
http://10.0.0.5/sonar |
If SonarQube is reachable only by IP, use the IP as is. If it's deployed under a subpath (e.g.
/sonar), include that in the URL as well.
Getting a SonarQube token
- Sign in to SonarQube with your account.
- Open My Account -> Security.
- In Generate Tokens, enter a token name and pick type User Token.
- Click Generate — the token is shown only once. Copy it immediately.
- Use the token value as
SONAR_TOKEN.
If a token is lost, you have to regenerate it — SonarQube doesn't display existing tokens again.
The server uses HTTP Bearer auth, passing the token in the Authorization header — this is the standard SonarQube Community Build scheme for user tokens.
Running
SONAR_URL=http://sonar.example.com SONAR_TOKEN=your_token \
java -jar build/libs/sonar-mcp-server.jar
The server runs over stdio. After a successful start it opens no HTTP port and waits for MCP requests over stdin/stdout.
Logs are written to ${SONAR_MCP_DATA_DIR:-~/.sonar-mcp-server}/logs/sonar-mcp-server.log.
The file rotates by date and size: 10MB, retention 30 days, total cap 512MB.
Docker
The image is published to GHCR with every release:
docker run -i --rm -e SONAR_URL=https://sonar.example.com -e SONAR_TOKEN=your_token ghcr.io/igorolv/sonar-mcp-server:latest
The same command is what an MCP client should launch (-i keeps stdin open for the stdio
transport). Mount a host directory at /data to keep logs between runs. If SonarQube runs on the
same machine, use its host name rather than localhost, or add --network host on Linux.
To build the image locally: docker build -t sonar-mcp-server .
Connecting to an AI client
{
"command": "java",
"args": ["-jar", "<absolute-path>/sonar-mcp-server.jar"],
"env": {
"SONAR_URL": "http://sonar.example.com",
"SONAR_TOKEN": "your_token"
}
}
Where exactly:
| Client | How to connect |
|---|---|
| Claude Code | claude mcp add --scope user -e SONAR_URL=... -e SONAR_TOKEN=... -- sonar java -jar /path/to/sonar-mcp-server.jar |
| Qwen Code | ~/.qwen/settings.json -> "mcpServers" -> "sonar", or qwen mcp add --scope user -e SONAR_URL=... -e SONAR_TOKEN=... sonar java -jar /path/to/sonar-mcp-server.jar |
| VS Code | .vscode/mcp.json -> "servers" -> "sonar" |
| Cursor | .cursor/mcp.json -> "mcpServers" -> "sonar" |
| Claude Desktop | claude_desktop_config.json -> "mcpServers" -> "sonar" |
For CLI clients there are also commands to view and remove the registration: claude mcp list / claude mcp remove --scope user sonar (similarly for qwen).
After adding, restart the client.
Example AI-agent prompts
Find and fix Sonar issues in project my-project
Show the top 10 rules by number of open issues in project my-project
Show Sonar issues under src/main/java/com/example/foo
Operations and security
This MCP server is meant to run locally next to the AI client. It opens no HTTP port and accepts no incoming network connections: the client starts the JAR as a child process and talks to it over stdin/stdout.
Access model
- The server acts with the rights of the SonarQube user whose token is in
SONAR_TOKEN. - All MCP tools are read-only: the server does not create, modify, or delete issues, hotspots, rules, or projects.
- Available projects and issues are determined by the user's permissions in SonarQube. If the user can't see a project in SonarQube, the server shouldn't be able to access it either.
- Treat the token as a secret. Don't commit it to the repository, shell scripts,
.vscode/mcp.json,.cursor/mcp.json, or any other shared project files.
What data is sent to the AI client
The AI client receives exactly the data it requests through the MCP tools:
- the list of issues with rule, severity, type, file path, line number, message, tags, SCM author;
- issue change history;
- Sonar rule descriptions (including HTML/markdown);
- source-code snippets around issue locations (via
getIssueSnippets); - Security Hotspots and their details.
Before connecting to an external or cloud-based AI client, check your company's internal policies: source code may contain trade secrets.
Diagnostics
Environment check:
java -version
echo "$SONAR_URL"
test -n "$SONAR_TOKEN" && echo "SONAR_TOKEN is set"
SonarQube web-api access check (HTTP Bearer auth with the token):
curl -H "Authorization: Bearer $SONAR_TOKEN" "$SONAR_URL/api/components/search?qualifiers=TRK&p=1&ps=1"
The expected response is a JSON list of projects. 401 Unauthorized means the token is invalid or expired; 403 means the user lacks permission for the API.
Build check:
./gradlew test
./gradlew build
Integration tests against a live SonarQube:
SONAR_URL=<url> SONAR_TOKEN=<token> ./gradlew integrationTest
Integration tests require a reachable SonarQube and real data. Unit tests exclude the integration tag by default.
Known operational limitations
- HTTP timeouts and retry policy aren't separately configurable yet.
- The Sonar API uses page-based pagination (
p/ps); the tools acceptoffset/limit, and an offset that is not a multiple oflimitis rounded down to the nearest page boundary. Sonar also capspsat 500. componentPathPrefixis a client-side filter: the server pages through the project's issues / hotspots and keeps those whosecomponentPathstarts with the prefix (directory-boundary safe). The scan is capped (SONAR_MCP_PATH_FILTER_MAX_SCANNED_ISSUES, default 10000); when the cap is hit, the response setspathPrefixTruncated=trueand the caller should tighten the prefix.- The
authorfield onIssueis the SCM author of the line where the issue occurred (populated by Sonar when an SCM provider is configured). Sonar doesn't return separatescmAuthor/scmDatefields inissues/search; for line-level SCM usegetIssueSnippets.
Project layout
├── src/main/java/ru/it_spectrum/ai/sonar/mcp/
│ ├── SonarMcpServerApplication.java — Spring Boot entry point
│ ├── api/ — stable MCP wire format: records returned by tools/services
│ │ ├── Issue.java, IssuePage.java, IssueDetails.java, IssueLocation.java, IssueFlow.java, IssueImpact.java, IssueSnippets.java
│ │ ├── Project.java, ProjectPage.java, ProjectOverview.java, ProjectMetrics.java, ProjectComponent.java, ProjectComponentPage.java
│ │ ├── RuleDetails.java, RuleSection.java
│ │ ├── Hotspot.java, HotspotDetails.java, HotspotPage.java, HotspotRule.java
│ │ ├── SourceSnippet.java, SnippetLine.java
│ │ ├── ChangelogEntry.java, ChangelogDiff.java
│ │ ├── TextRange.java, FacetCount.java, BranchAdvisory.java
│ │ ├── ProjectIssuesSummary.java, ProjectIssuesBreakdown.java, ModuleIssuesSummary.java
│ │ ├── ProjectBranch.java, ProjectBranches.java, ProjectPullRequest.java, ProjectPullRequests.java
│ │ ├── QualityGateStatus.java, QualityGateCondition.java
│ │ └── Opaque.java
│ ├── client/
│ │ ├── SonarClient.java — SonarQube web-api wrapper
│ │ └── model/ — raw DTOs of the SonarQube web-api, not exposed directly via MCP
│ │ └── Sonar*.java
│ ├── config/
│ │ ├── SonarClientProperties.java — url + token from env
│ │ ├── SonarMcpProperties.java — all sonar-mcp.* runtime settings
│ │ ├── SonarConfig.java — RestClient with Bearer auth
│ │ ├── McpServerConfig.java — stdio MCP customizer with immediateExecution(true)
│ │ └── JsonConfig.java — ObjectMapper for MCP JSON
│ ├── service/
│ │ ├── ProjectService.java
│ │ ├── IssueService.java
│ │ ├── RuleService.java — with in-memory rule cache
│ │ ├── SnippetService.java
│ │ ├── HotspotService.java
│ │ ├── PaginationHelper.java — offset/limit -> p/ps
│ │ └── SonarMappers.java — client.model -> api mapping
│ └── tools/
│ ├── ProjectTools.java — 5 MCP tools
│ ├── IssueTools.java — 5 MCP tools
│ ├── RuleTools.java — 1 MCP tool
│ ├── HotspotTools.java — 2 MCP tools
│ ├── ToolDescriptions.java — shared @McpTool / @McpToolParam description constants
│ ├── SonarPrompts.java — MCP prompts (analyzePath, fixPath, fixFile, investigateIssue, reviewPullRequest)
│ ├── RefResolver.java — branch/pullRequest resolution with default-branch fallback
│ └── ToolLogger.java
└── src/main/resources/
├── application.yml — MCP server configuration (stdio)
└── logback-spring.xml — logging configuration
Troubleshooting
- "Gradle requires JVM 17 or later" — set
JAVA_HOMEto a JDK 25+. - Connection refused / 401 — check URL and token. Test:
curl -H "Authorization: Bearer $SONAR_TOKEN" "$SONAR_URL/api/components/search?qualifiers=TRK&p=1&ps=1". - 403 Forbidden — the token user has no rights on the project or on the web-api. Check the role in SonarQube.
- Package/module scope returns 0 issues — pass the path-style prefix as
componentPathPrefix(e.g.bc-doc/src/main/java/ru/foo), not a Sonar component key. Convert Java/Kotlin package dots to slashes. The filter is directory-boundary safe, sobc-doc/srcwill not matchbc-doc/srcExtra. pathPrefixTruncated=truein the response — the client-side scan hitSONAR_MCP_PATH_FILTER_MAX_SCANNED_ISSUESbefore reaching the end. Tighten the prefix to reduce the scan, or raise the cap if 10k is genuinely not enough for your project.
SonarQube Community Build MCP questions
How do I add SonarQube Community Build MCP to Claude Code?
Run claude mcp add --env 'SONAR_TOKEN=<YOUR_SONAR_TOKEN>' --env 'SONAR_URL=<SONAR_URL>' sonar-mcp-server -- docker run -i --rm ghcr.io/igorolv/sonar-mcp-server:0.1.0 in your terminal. Add --scope user to make it available in every project.
How do I add SonarQube Community Build MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does SonarQube Community Build MCP provide?
It exposes 13 tools, including getHotspot, listHotspots, getIssue, getIssueSnippets, getProjectIssuesBreakdown.
Is the server capable of modifying SonarQube data?
No, the server is read-only by design and cannot create, update, or delete anything in SonarQube.
What version of SonarQube is required?
The server requires a SonarQube Community Build version 26.4 or higher.
Can the server access source code snippets?
Yes, it can fetch source-code snippets around issue locations, which is useful if the repository is not available locally.