McpSonarQube 0.1.0
dotnet tool install --global McpSonarQube --version 0.1.0
dotnet new tool-manifest
dotnet tool install --local McpSonarQube --version 0.1.0
#tool dotnet:?package=McpSonarQube&version=0.1.0
nuke :add-package McpSonarQube --version 0.1.0
McpSonarQube
Servidor MCP somente leitura para SonarQube Server e SonarCloud. O agente consulta Quality Gate, métricas, issues, hotspots, exclusões e branches antes do merge.
Funciona no Gemini CLI, Claude Desktop, Cursor, Copilot e Windsurf. O foco da documentação é o Gemini CLI.
O token fica na máquina de quem usa. O pacote não guarda segredo, URL nem organização.
Repositório: https://github.com/SouzaMatheus-dev/mcp-sonarqube
Escopo
Leitura da API REST. O servidor não muda Quality Gate, não resolve issue e não grava exclusão.
| Edição | O que responde |
|---|---|
| SonarQube Community 9.x e 10.x | Quality Gate, métricas, issues, hotspots e settings |
| Developer, Enterprise e Data Center | O mesmo, mais branches e pull requests |
| SonarCloud | O mesmo, com SONARQUBE_ORGANIZATION |
Requisitos
| Item | Detalhe |
|---|---|
| .NET | SDK 8 para desenvolver. A ferramenta instalada usa o runtime exigido pelo dotnet tool |
| Token | User token do SonarQube ou SonarCloud. Senha de usuário não autentica esta API |
| Rede | HTTP ou HTTPS até o host configurado |
Gere o token em My Account → Security → Generate Tokens. Cole o valor só no env do cliente MCP.
Instalação
dotnet tool install --global McpSonarQube
dotnet tool update --global McpSonarQube
O comando instalado é sonarqube-mcp.
Gemini CLI
Arquivo global: ~/.gemini/settings.json. No projeto, o mesmo bloco vai em .gemini/settings.json.
{
"mcpServers": {
"sonarqube": {
"command": "sonarqube-mcp",
"timeout": 60000,
"trust": true,
"env": {
"SONARQUBE_HOST_URL": "http://localhost:9000",
"SONARQUBE_TOKEN": "seu_user_token"
}
}
}
}
SonarCloud:
{
"mcpServers": {
"sonarqube": {
"command": "sonarqube-mcp",
"timeout": 60000,
"trust": true,
"env": {
"SONARQUBE_HOST_URL": "https://sonarcloud.io",
"SONARQUBE_TOKEN": "seu_user_token",
"SONARQUBE_ORGANIZATION": "sua-organizacao",
"SONARQUBE_AUTH": "bearer"
}
}
}
}
trust: true libera as ferramentas de leitura sem pedir confirmação a cada chamada. O token continua só nesse arquivo local.
Sem instalação global, a partir do código:
{
"mcpServers": {
"sonarqube": {
"command": "dotnet",
"args": ["run", "--project", "/caminho/para/src/SonarQube.McpServer/SonarQube.McpServer.csproj"],
"timeout": 120000,
"trust": true,
"env": {
"SONARQUBE_HOST_URL": "http://localhost:9000",
"SONARQUBE_TOKEN": "seu_user_token"
}
}
}
}
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"sonarqube": {
"command": "dotnet",
"args": ["run", "--project", "/path/to/src/SonarQube.McpServer/SonarQube.McpServer.csproj"],
"env": {
"SONARQUBE_HOST_URL": "https://sonar.example.com",
"SONARQUBE_TOKEN": "seu_user_token"
}
}
}
}
Cursor
{
"mcpServers": {
"sonarqube": {
"command": "sonarqube-mcp",
"env": {
"SONARQUBE_HOST_URL": "http://localhost:9000",
"SONARQUBE_TOKEN": "seu_user_token"
}
}
}
}
Docker
docker build -t sonarqube-mcp .
docker run -i --rm \
-e SONARQUBE_HOST_URL=http://localhost:9000 \
-e SONARQUBE_TOKEN=seu_user_token \
sonarqube-mcp
O processo fala MCP por stdin e stdout. Logs vão para stderr. O token não é impresso.
Configuração
Nada disso entra no repositório. Variável vazia cai no padrão.
| Variável | Padrão | Função |
|---|---|---|
SONARQUBE_HOST_URL ou SONAR_HOST_URL |
http://localhost:9000 |
Host do SonarQube Server ou https://sonarcloud.io |
SONARQUBE_TOKEN ou SONAR_TOKEN |
vazio | User token. Nunca senha |
SONARQUBE_ORGANIZATION ou SONAR_ORGANIZATION |
vazio | Obrigatória no SonarCloud para buscar projetos |
SONARQUBE_AUTH ou SONAR_AUTH |
basic |
basic (token como usuário, senha vazia) ou bearer |
SONARQUBE_SKIP_TLS_VERIFY |
false |
Aceita certificado TLS não confiável. Use só em laboratório |
O modo basic é o da API do SonarQube: Authorization: Basic base64(token + ":"). Use bearer se o token do SonarCloud exigir esse esquema.
Uso
sonar_validar_conexao.- Se a chave do projeto não estiver na conversa,
sonar_search_projects. sonar_get_quality_gate,sonar_get_measures,sonar_search_issues,sonar_check_exclusionsesonar_list_branches.
Passe branch ou pullRequest, nunca os dois. Para uma lista curta de issues, use severities BLOCKER e CRITICAL.
Catálogo
| Ferramenta | Uso |
|---|---|
sonar_validar_conexao |
Host, versão e se o token autentica, sem devolver o segredo |
sonar_search_projects |
Acha a projectKey |
sonar_get_quality_gate |
PASSED, FAILED ou WARN, com condições fora do limite |
sonar_get_measures |
Cobertura, ratings, dívida, duplicação, bugs, vulnerabilidades e code smells |
sonar_search_issues |
Issues abertas com arquivo, linha, severidade e débito. SECURITY_HOTSPOT lista hotspots TO_REVIEW |
sonar_check_exclusions |
sonar.coverage.exclusions e sonar.exclusions, com aviso em padrão amplo |
sonar_list_branches |
Branches e pull requests analisados. No Community a resposta explica a limitação da edição |
PASSED corresponde a OK na API. FAILED corresponde a ERROR.
Métricas padrão de sonar_get_measures: new_coverage, coverage, new_reliability_rating, reliability_rating, new_security_rating, security_rating, new_security_hotspots_reviewed, sqale_index, new_technical_debt, duplicated_lines_density, code_smells, bugs, vulnerabilities.
Desenvolvimento
dotnet test SonarQube.McpServer.slnx
A publicação no NuGet dispara na tag v*. O workflow .github/workflows/publish.yml testa, empacota e envia com Trusted Publishing, na conta matneves. O passo a passo da primeira vez está em docs/publicacao-nuget.md.
Publicação local em arquivo único, sem AOT. A descoberta das ferramentas usa reflexão, então Native AOT fica desligado.
dotnet publish src/SonarQube.McpServer/SonarQube.McpServer.csproj -c Release -p:PublishSingleFile=true
Solução de problemas
| Sintoma | O que fazer |
|---|---|
Token ausente |
Preencha SONARQUBE_TOKEN no env do cliente. Não commite o valor. |
401 e texto sobre user token |
A senha da conta não vale. Gere um token em My Account → Security. |
403 |
O token precisa de Browse no projeto. |
SONARQUBE_ORGANIZATION |
No SonarCloud a busca de projetos exige a organização. |
branch ou pullRequest, não os dois |
Refaça a chamada com um só. |
| Branches vazias com aviso de Developer | A edição Community não expõe /api/project_branches/list. Quality Gate e issues seguem disponíveis. |
| Timeout de 30 segundos | Confira rede, VPN e SONARQUBE_HOST_URL. |
Licença
MIT.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0 | 144 | 10/20/2026 |