sonar-mcp-server

Servidor MCP Sonar

Um servidor MCP local que fornece acesso somente leitura a uma instância do SonarQube Community Build (26.4+) por meio de sua web-api. Ele permite que agentes de IA (Claude Code, Cursor, VS Code Copilot, etc.) obtenham a lista de problemas de um projeto, os arquivos e locais onde ocorrem, descrições de regras, trechos de código-fonte ao redor dos problemas e Security Hotspots.

Cenário típico: "encontre e corrija problemas do Sonar em tal projeto" — o LLM chama listIssues, opcionalmente getRule e getIssueSnippets, e edita os arquivos localmente.

Por que este servidor

Existe um servidor MCP oficial da SonarSource, mas ele tem como alvo o SonarQube 10+ (e o SonarCloud) e pressupõe uma implantação no estilo nuvem. Este servidor foi criado para instalações auto-hospedadas do SonarQube Community Build 26.4+ que expõem a web-api clássica /api/. Ele suporta tanto a Standard Experience quanto o modo MQR, lidando com impactos por qualidade de software quando a instância está no modo MQR.

Ele também é intencionalmente mais restrito em escopo:

• Somente leitura por design. O servidor nunca cria, atualiza ou exclui nada no SonarQube — sem marcar problemas como falso-positivo, sem editar comentários, sem endpoints administrativos. As permissões de escrita do token no SonarQube são irrelevantes porque o servidor nunca chama esses endpoints.
• Conjunto de ferramentas selecionado. Em vez de espelhar a superfície da API do SonarQube, o servidor expõe um conjunto pequeno e focado de ferramentas (13 no total) escolhidas para um único fluxo de trabalho: deixar um agente de IA ler as descobertas do Sonar e corrigir o código com base nelas. Listar componentes, problemas e hotspots, detalhar uma única descoberta, buscar a explicação da regra e obter o trecho de código-fonte ao redor do local — e só. Qualquer coisa fora desse ciclo "diagnosticar -> corrigir o código localmente" é deliberadamente deixada de fora para manter a lista de ferramentas pequena e as escolhas do agente inequívocas.

Em resumo: uma ponte focada e somente leitura de uma instância auto-hospedada do SonarQube Community Build para um agente de IA de codificação.

Início rápido

1. Instale o JDK 25+.
2. Baixe o sonar-mcp-server.jar da última versão, ou compile você mesmo: ./gradlew bootJar (veja Build). Uma imagem Docker também é publicada.
3. Obtenha a URL do seu SonarQube e o token de usuário (veja Configuração).
4. Adicione o JAR à configuração MCP do seu cliente (veja Conectando a um cliente de IA).

Para o Claude Code, isso é um único comando:

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

Arquitetura

O servidor suporta apenas o transporte stdio.

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

O cliente de IA inicia o servidor como um processo filho; a comunicação usa o protocolo MCP via stdin/stdout. O servidor não abre nenhuma porta HTTP e não aceita conexões de entrada.

Ferramentas

O servidor exporta 13 ferramentas MCP somente leitura.

Projetos

Ferramenta	Descrição
listProjects	Lista de projetos do SonarQube. Parâmetros: query (substring do nome), limit, offset. Retorna key, name, qualifier.
listComponents	Pesquisa/navega componentes dentro de um projeto usando a árvore de componentes do Sonar. Parâmetros: projectKey, query, qualifiers, branch / pullRequest, limit, offset. Retorna valores opacos de key do componente, além de path, qualifier, nome, linguagem e projeto. Use os valores de key retornados inalterados como listIssues.componentKeys; não passe nomes de pacotes Java diretamente como chaves de componente.
getProject	Visão geral do projeto: informações de cabeçalho (nome, qualificador, visibilidade, descrição, versão, data da última análise), status do quality gate com condições reprovadas e métricas selecionadas (ncloc, bugs, vulnerabilidades, security hotspots, code smells, cobertura, densidade de linhas duplicadas, dívida técnica em minutos, status de alerta). Parâmetros: projectKey, branch (opc.), pullRequest (opc.).
listProjectBranches	Lista de branches analisadas para o projeto. Cada entrada: name, isMain, type (LONG/SHORT/BRANCH), excludedFromPurge, analysisDate, qualityGateStatus, além das contagens de bugs/vulnerabilidades/codeSmells. Sem paginação — o Sonar retorna todas as branches de uma vez.
listProjectPullRequests	Lista de análises de PR para o projeto. Cada entrada: key do PR (use como pullRequest= em outros lugares), title, branch (head), base, url, analysisDate, qualityGateStatus, além das contagens de bugs/vulnerabilidades/codeSmells. Lista vazia se a instalação do Sonar não tiver integração com DevOps.

Problemas

Ferramenta	Descrição
listIssues	Lista plana de problemas de um projeto. Parâmetros: projectKey (obrigatório, a menos que haja padrão), componentPathPrefix (opc.) — um único filtro de subárvore ou arquivo relativo à raiz do projeto Sonar (ex.: bc-doc/src/main/java/ru/foo ou bc-doc/src/main/java/ru/foo/Bar.java); converta pontos de pacotes Java/Kotlin em barras; respeita limites de diretório (bc-doc/src não corresponde a bc-doc/srcExtra). Além de severities, types, statuses, rules, branch / pullRequest (mutuamente exclusivos), resolved, limit, offset. Por padrão, retorna apenas problemas abertos (resolved=false, status OPEN/CONFIRMED/REOPENED). Cada item contém a regra, severidade, tipo, status, caminho do arquivo, linha, textRange primário e fluxos secundários para regras entre arquivos. Quando componentPathPrefix é usado, o servidor verifica o projeto e filtra no lado do cliente; a verificação é limitada (padrão de 10000 problemas) — se o limite for atingido, pathPrefixTruncated=true na resposta.
getIssue	Detalhes de um único problema por chave, além do histórico de alterações (changelog). Aceita branch / pullRequest opcionais.
getIssueSnippets	Trechos de código-fonte ao redor de todos os locais do problema (primário mais fluxos para regras entre arquivos). Para cada local: componentPath, linguagem e uma matriz de linhas de código-fonte com informações de SCM. Útil quando o repositório não está disponível localmente ou você precisa ver exatamente a versão do arquivo que o Sonar analisou. Aceita branch / pullRequest opcionais — importante quando o problema está em um ref não principal cujos arquivos diferem do principal.
getProjectIssuesSummary	Resumo agregado de problemas abertos em um projeto: total mais detalhamentos por severidade, tipo, status, regra, tag e autor SCM. Parâmetros espelham listIssues (incl. componentPathPrefix), exceto paginação.
getProjectIssuesBreakdown	Agregação de problemas em vários módulos por módulo lógico e regra. O módulo é derivado do primeiro segmento de componentPath. Parâmetros espelham getProjectIssuesSummary.

Regras

Ferramenta	Descrição
getRule	Detalhes de uma regra do Sonar por chave (ex.: java:S1234): título, severidade, tipo, linguagem, tags, seções de descrição (introdução, causa raiz, como corrigir, recursos). Suportado por um cache em memória — chamadas repetidas são gratuitas.

Security Hotspots

Ferramenta	Descrição
listHotspots	Lista de Security Hotspots de um projeto. Hotspots são uma categoria separada dos problemas, marcando pontos que exigem revisão manual de segurança. Por padrão, o Sonar retorna hotspots no status TO_REVIEW. Parâmetros: projectKey, componentPathPrefix (opc.) — mesma semântica de prefixo do listIssues, status (opc.), branch / pullRequest (opc., mutuamente exclusivos), limit, offset. Sujeito ao mesmo limite de verificação no lado do cliente (flag pathPrefixTruncated na resposta).
getHotspot	Detalhes do Security Hotspot: descrição completa da regra (risco, vulnerabilidade, recomendações de correção), textRange primário, fluxos secundários, changelog. As chaves de hotspot são globalmente únicas, portanto nenhum parâmetro branch/pullRequest é necessário.

Todas as ferramentas são somente leitura — nenhum dado no SonarQube é modificado.

Trabalhando com branches e pull requests

O Sonar analisa uma branch e um pull request como dois escopos distintos e mutuamente exclusivos. A web-api do Sonar aceita branch= ou pullRequest= em uma única solicitação, nunca ambos.

• branch — branches de longa duração (main, develop, feature/...). Resolvidas como: argumento explícito branch → SONAR_DEFAULT_BRANCH → nenhum (o Sonar usa a branch principal do projeto).
• pullRequest — a chave de PR do Sonar, geralmente o número do PR/MR. Independente das análises de branch; as análises de PR geralmente contêm as descobertas mais relevantes para o trabalho em andamento. As chaves de pull request nunca recorrem a um padrão de nível de servidor — passe-as explicitamente.

Passar branch e pullRequest juntos para a mesma chamada de ferramenta é um erro. Use listProjectBranches / listProjectPullRequests para descobrir refs disponíveis.

O escopo da branch é essencial. Cada branch do Sonar é uma análise separada: as contagens de problemas abertos em main e em uma branch de feature podem diferir muito, porque a branch de feature pode ter novas correções (ou novo código) que ainda não foram mescladas. Se o agente omitir silenciosamente branch=, ele lê de main (ou SONAR_DEFAULT_BRANCH) e pode perder o trabalho já feito em uma branch de feature — ou pior, corrigir o mesmo problema duas vezes. Quando o git local do usuário está em feature/..., os agentes devem chamar listProjectBranches primeiro, encontrar a branch Sonar correspondente e passá-la explicitamente para cada chamada de problema / resumo / detalhamento.

Como rede de segurança no lado do servidor, listIssues, getProjectIssuesSummary e getProjectIssuesBreakdown anexam um campo branchAdvisory à resposta quando (1) nem branch nem pullRequest foram passados E (2) o projeto tem outras branches analisadas no Sonar. O aviso carrega o nome da branch efetiva (principal) e a lista de branches não principais ordenadas pela analysisDate mais recente. O campo está ausente caso contrário.

Stack

• Java 25, Spring Boot 4.0.0, Spring AI MCP 2.0.0 (transporte stdio)
• Jackson 3 (tools.jackson) para JSON
• Gradle 9.3.1 com catálogo de versões (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

No Windows: .\gradlew.bat build.

Saída: build/libs/sonar-mcp-server.jar

Configuração

O servidor precisa de uma URL e token do SonarQube; o restante é opcional.

Variável	Descrição
SONAR_URL	URL base do SonarQube (ex.: http://sonar.example.com)
SONAR_TOKEN	Token de usuário do SonarQube
SONAR_DEFAULT_PROJECT_KEY	Chave de projeto padrão do SonarQube. Quando definida, listIssues, getProjectIssuesSummary, listHotspots podem ser chamadas sem projectKey.
SONAR_DEFAULT_BRANCH	Branch Sonar padrão. Quando definida, todas as ferramentas que reconhecem branch (listIssues, getIssue, getIssueSnippets, getProjectIssuesSummary, listHotspots) recorrem a esta branch quando branch é omitido. Sem ela, o Sonar usa a branch principal do projeto.
SONAR_MCP_DATA_DIR	Diretório de dados local do servidor; o padrão é ~/.sonar-mcp-server
SONAR_MCP_PAGINATION_DEFAULT_LIMIT	Limite de página padrão para ferramentas de lista; o padrão é 50
SONAR_MCP_PAGINATION_DEFAULT_OFFSET	Deslocamento padrão para ferramentas de lista; o padrão é 0
SONAR_MCP_PAGINATION_MAX_LIMIT	Limite máximo de página (a própria API do Sonar limita a 500); o padrão é 500
SONAR_MCP_SNIPPET_MAX_LINES	Reservado para um futuro limite de linhas por trecho; atualmente não usado (o Sonar escolhe a janela). O padrão é 50
SONAR_MCP_PATH_FILTER_MAX_SCANNED_ISSUES	Limite rígido de problemas/hotspots verificados no lado do cliente quando componentPathPrefix está definido; o padrão é 10000. Se o limite for atingido, a resposta carrega pathPrefixTruncated=true.

Grupos de ferramentas

O manifesto MCP tools/list é dividido em quatro grupos, cada um controlado por uma flag de ambiente. Todos os grupos estão ativos por padrão, portanto o manifesto padrão não é alterado. Desative um grupo para reduzir o manifesto — útil para modelos de contexto pequeno (local) que, de outra forma, seriam inundados com esquemas de ferramentas e saídas no início da sessão.

Variável	Ferramentas no grupo
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

Defina um sinalizador para false (ex.: SONAR_MCP_TOOLS_HOTSPOT=false) para remover as ferramentas desse grupo do manifesto.

Obtendo a URL do SonarQube

Abra o SonarQube em um navegador e copie o endereço da barra de localização sem o caminho — apenas o esquema e o host.

Na barra de endereço do navegador	Valor da URL
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

Se o SonarQube for acessível apenas por IP, use o IP como está. Se estiver implantado em um subcaminho (ex.: /sonar), inclua isso também na URL.

Obtendo um token do SonarQube

1. Entre no SonarQube com sua conta.
2. Abra Minha conta -> Segurança.
3. Em Gerar tokens, insira um nome para o token e escolha o tipo Token de usuário.
4. Clique em Gerar — o token é exibido apenas uma vez. Copie-o imediatamente.
5. Use o valor do token como SONAR_TOKEN.

Se um token for perdido, você precisará gerá-lo novamente — o SonarQube não exibe tokens existentes novamente.

O servidor usa autenticação HTTP Bearer, enviando o token no cabeçalho Authorization — este é o esquema padrão do SonarQube Community Build para tokens de usuário.

Execução

SONAR_URL=http://sonar.example.com SONAR_TOKEN=your_token \
  java -jar build/libs/sonar-mcp-server.jar

O servidor roda sobre stdio. Após uma inicialização bem-sucedida, ele não abre nenhuma porta HTTP e aguarda solicitações MCP via stdin/stdout.

Os logs são gravados em ${SONAR_MCP_DATA_DIR:-~/.sonar-mcp-server}/logs/sonar-mcp-server.log. O arquivo é rotacionado por data e tamanho: 10MB, retenção de 30 dias, limite total de 512MB.

Docker

A imagem é publicada no GHCR a cada lançamento:

docker run -i --rm   -e SONAR_URL=https://sonar.example.com   -e SONAR_TOKEN=your_token   ghcr.io/igorolv/sonar-mcp-server:latest

O mesmo comando é o que um cliente MCP deve executar (-i mantém o stdin aberto para o transporte stdio). Monte um diretório do host em /data para manter os logs entre execuções. Se o SonarQube rodar na mesma máquina, use o nome do host em vez de localhost, ou adicione --network host no Linux. Para construir a imagem localmente: docker build -t sonar-mcp-server .

Conectando a um cliente de IA

{
  "command": "java",
  "args": ["-jar", "<absolute-path>/sonar-mcp-server.jar"],
  "env": {
    "SONAR_URL": "http://sonar.example.com",
    "SONAR_TOKEN": "your_token"
  }
}

Onde exatamente:

Cliente	Como conectar
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", ou 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"

Para clientes CLI, também existem comandos para visualizar e remover o registro: claude mcp list / claude mcp remove --scope user sonar (similarmente para qwen).

Após adicionar, reinicie o cliente.

Exemplos de prompts para agentes de IA

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

Operações e segurança

Este servidor MCP foi feito para rodar localmente ao lado do cliente de IA. Ele não abre nenhuma porta HTTP e não aceita conexões de rede de entrada: o cliente inicia o JAR como um processo filho e se comunica com ele via stdin/stdout.

Modelo de acesso

• O servidor age com os direitos do usuário do SonarQube cujo token está em SONAR_TOKEN.
• Todas as ferramentas MCP são somente leitura: o servidor não cria, modifica ou exclui issues, hotspots, regras ou projetos.
• Os projetos e issues disponíveis são determinados pelas permissões do usuário no SonarQube. Se o usuário não puder ver um projeto no SonarQube, o servidor também não deverá conseguir acessá-lo.
• Trate o token como um segredo. Não o envie para o repositório, scripts de shell, .vscode/mcp.json, .cursor/mcp.json ou qualquer outro arquivo compartilhado do projeto.

Quais dados são enviados ao cliente de IA

O cliente de IA recebe exatamente os dados que solicita por meio das ferramentas MCP:

• a lista de issues com regra, severidade, tipo, caminho do arquivo, número da linha, mensagem, tags, autor SCM;
• histórico de alterações do issue;
• descrições de regras do Sonar (incluindo HTML/markdown);
• trechos de código-fonte ao redor dos locais dos issues (via getIssueSnippets);
• Security Hotspots e seus detalhes.

Antes de conectar a um cliente de IA externo ou baseado em nuvem, verifique as políticas internas da sua empresa: o código-fonte pode conter segredos comerciais.

Diagnóstico

Verificação do ambiente:

java -version
echo "$SONAR_URL"
test -n "$SONAR_TOKEN" && echo "SONAR_TOKEN is set"

Verificação de acesso à web-api do SonarQube (autenticação HTTP Bearer com o token):

curl -H "Authorization: Bearer $SONAR_TOKEN" "$SONAR_URL/api/components/search?qualifiers=TRK&p=1&ps=1"

A resposta esperada é uma lista JSON de projetos. 401 Unauthorized significa que o token é inválido ou expirou; 403 significa que o usuário não tem permissão para a API.

Verificação de build:

./gradlew test
./gradlew build

Testes de integração contra um SonarQube ativo:

SONAR_URL=<url> SONAR_TOKEN=<token> ./gradlew integrationTest

Os testes de integração exigem um SonarQube acessível e dados reais. Os testes de unidade excluem a tag integration por padrão.

Limitações operacionais conhecidas

• Timeouts HTTP e política de repetição ainda não são configuráveis separadamente.
• A API do Sonar usa paginação baseada em páginas (p/ps); as ferramentas aceitam offset/limit, e um deslocamento que não seja múltiplo de limit é arredondado para baixo até o limite de página mais próximo. O Sonar também limita ps a 500.
• componentPathPrefix é um filtro do lado do cliente: o servidor percorre os issues/hotspots do projeto e mantém aqueles cujo componentPath começa com o prefixo (seguro em limites de diretório). A varredura é limitada (SONAR_MCP_PATH_FILTER_MAX_SCANNED_ISSUES, padrão 10000); quando o limite é atingido, a resposta define pathPrefixTruncated=true e o chamador deve restringir o prefixo.
• O campo author em Issue é o autor SCM da linha onde o issue ocorreu (preenchido pelo Sonar quando um provedor SCM está configurado). O Sonar não retorna campos separados scmAuthor/scmDate em issues/search; para SCM em nível de linha, use getIssueSnippets.

Estrutura do projeto

├── 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

Solução de problemas

• "Gradle requires JVM 17 or later" — defina JAVA_HOME para um JDK 25+.
• Conexão recusada / 401 — verifique a URL e o token. Teste: curl -H "Authorization: Bearer $SONAR_TOKEN" "$SONAR_URL/api/components/search?qualifiers=TRK&p=1&ps=1".
• 403 Forbidden — o usuário do token não tem direitos sobre o projeto ou sobre a web-api. Verifique o papel no SonarQube.
• Escopo de pacote/módulo retorna 0 issues — passe o prefixo no formato de caminho como componentPathPrefix (ex.: bc-doc/src/main/java/ru/foo), não uma chave de componente do Sonar. Converta pontos de pacotes Java/Kotlin em barras. O filtro é seguro em limites de diretório, então bc-doc/src não corresponderá a bc-doc/srcExtra.
• pathPrefixTruncated=true na resposta — a varredura do lado do cliente atingiu SONAR_MCP_PATH_FILTER_MAX_SCANNED_ISSUES antes de chegar ao fim. Restrinja o prefixo para reduzir a varredura, ou aumente o limite se 10k realmente não for suficiente para o seu projeto.