sonarqube-mcp

An MCP server that exposes SonarQube data as AI agent tools. 43 tools — the most comprehensive SonarQube MCP implementation available. Covers projects, issues, quality gates, hotspots, coverage, SCM, webhooks, metrics history, worst-metric ranking, project introspection, and composite workflow tools.

Dogfooding: this project is checked via its own tools.

Works with any SonarQube edition — Cloud, Developer, Enterprise, and Community Edition on localhost. No Docker/JVM needed, starts in ~0.1s.

Quick start

Pin to a specific version: ["npx", "-y", "github:metalralf/sonarqube-mcp#1.7.0"]
Omit #1.7.0 for the latest (unstable) development version.

Minimum config (3 required env vars)

Claude Desktop / VS Code MCP / Cursor / any MCP client:

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "github:metalralf/sonarqube-mcp#1.7.0"],
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_...",
        "SONARQUBE_PROJECT": "my_project"
      }
    }
  }
}

opencode (uses mcp key instead of mcpServers):

{
  "mcp": {
    "sonarqube": {
      "type": "local",
      "command": ["npx", "-y", "github:metalralf/sonarqube-mcp#1.7.0"],
      "enabled": true,
      "environment": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_...",
        "SONARQUBE_PROJECT": "my_project"
      }
    }
  }
}

Full config (all options)

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "github:metalralf/sonarqube-mcp"],
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_...",
        "SONARQUBE_PROJECT": "my_project",
        "SONARQUBE_TOOLSETS": "issues,quality",
        "SONARQUBE_READ_ONLY": "false",
        "SONARQUBE_TRANSPORT": "stdio",
        "SONARQUBE_AUTH_SCHEME": "basic",
        "SONARQUBE_ORGANIZATION": "",
        "SONARQUBE_HTTP_HOST": "127.0.0.1",
        "SONARQUBE_HTTP_PORT": "8080",
        "SONARQUBE_HTTP_ALLOWED_ORIGINS": "*",
        "SONARQUBE_DISABLE_DOCKER": "false",
        "SONARQUBE_DOCKER_IMAGE": "sonarsource/sonar-scanner-cli",
        "SONARQUBE_DOCKER_FLAGS": "--network=host",
        "SONARQUBE_DOCKER_MOUNT_PATH": "/usr/src",
        "SONARQUBE_SCANNER_TIMEOUT": "300000",
        "SONARQUBE_API_TIMEOUT": "5000",
        "SONARQUBE_SOURCE_CONTEXT": "2"
      }
    }
  }
}

Tools (43)

Composite / Workflow (8 tools)

Discovery & Status (7 tools)

Quality Gates & Measures (4 tools)

Issues (5 tools)

Security Hotspots (3 tools)

Source & SCM (3 tools)

Branches & Pull Requests (2 tools)

Coverage (2 tools)

Duplications (2 tools)

Analysis & Metrics (3 tools)

Administration (5 tools)

Supported Languages

Analysis and detection for all major languages — including C# (which the official SonarQube MCP server's code analysis does not support).

Configuration

Environment variables

All configuration is via env vars. None are required at module scope — they're read lazily at call time.

Connection

Transport

Scanner

Toolset

Toolset filtering

"environment": { "SONARQUBE_TOOLSETS": "issues,quality" }

Read-only mode

SONARQUBE_READ_ONLY=true disables: sonar_set_issue_status, sonar_change_hotspot_status, sonar_run_analysis, sonar_setup_scanner.

HTTP transport

Set SONARQUBE_TRANSPORT=http for REST API access:

"environment": { "SONARQUBE_TRANSPORT": "http", "SONARQUBE_HTTP_PORT": "8080" }

curl -X POST http://localhost:8080/tools/sonar_ping -H 'Content-Type: application/json' -d '{}'
curl -X POST http://localhost:8080/tools/sonar_issues -H 'Content-Type: application/json' -d '{"projectKey":"my_project","compact":true}'

Deployment

Docker Compose (quick start)

cp .env.example .env
# edit .env with your SonarQube credentials
docker compose up --build

The server runs at http://localhost:8080. Configure SONARQUBE_READ_ONLY=true for team deployments. Set SONARQUBE_HTTP_ALLOWED_ORIGINS for CORS-enabled web clients.

Kubernetes (Helm)

# With inline token
helm install sonarqube-mcp ./charts/sonarqube-mcp \
  --set sonarqubeUrl=http://sonarqube:9000 \
  --set sonarqubeToken=squ_...

# With an existing Secret
kubectl create secret generic sq-token --from-literal=SONARQUBE_TOKEN=squ_...
helm install sonarqube-mcp ./charts/sonarqube-mcp \
  --set sonarqubeUrl=http://sonarqube:9000 \
  --set existingSecret=sq-token

Docker build (manual)

docker build -t sonarqube-mcp .
docker run --rm -e SONARQUBE_URL=http://localhost:9000 -e SONARQUBE_TOKEN=squ_... sonarqube-mcp

Agent usage guidelines

1. sonar_analysis_status — check project state first
2. sonar_summary — full picture in one call
3. sonar_ping — quick health check
4. sonar_quality_gate — pass/fail + failing conditions
5. sonar_list_quality_gates — browse available gates
6. sonar_measures — drill into metrics
7. sonar_worst_metrics — find problematic files
8. sonar_list_branches / sonar_list_pull_requests — pick branch/PR
9. sonar_issues — search with filters, compact mode
10. sonar_issues_summary — quick counts
11. sonar_new_issues — delta since last analysis
12. sonar_metrics_history — coverage/code-smell trends
13. sonar_rule — explain any rule
14. sonar_source / sonar_scm_info — source + git blame
15. sonar_hotspots — security review
16. sonar_hotspot_details — drill into hotspot
17. sonar_change_hotspot_status — mark reviewed
18. sonar_coverage_files — find under-tested files
19. sonar_file_coverage_details — per-file coverage
20. sonar_search_duplicated_files / sonar_duplications — find/fix dup
21. sonar_issues_bulk_transition — batch status changes
22. sonar_set_issue_status — mark resolved
23. sonar_run_analysis — confirm fixes

Token types

Local development setup

git clone <repo>
cd sonarqube-mcp
pnpm install

# Run from local checkout:
node src/index.mjs

Branch workflow

Version bumps

Setting up SonarQube locally

docker run -d --name sonarqube -p 9000:9000 sonarqube:community

Open http://localhost:9000, log in with admin/admin, generate a token.

Create sonar-project.properties:

sonar.host.url=http://localhost:9000
sonar.projectKey=my_project
sonar.sources=src
sonar.javascript.lcov.reportPaths=coverage/lcov.info

Run:

pnpm exec sonar-scanner -Dsonar.token=squ_...

Ecosystem Comparison

What makes this project unique

Features no other SonarQube MCP implementation has:

• Compact mode — strips verbose fields for LLM token efficiency
• Issue delta — sonar_new_issues since last analysis
• Metric history / trends — coverage and code-smell trajectory
• Worst-metric ranking — find files with worst coverage, highest duplication
• Bulk issue transitions — transition many issues at once
• Project creation — create SonarQube projects via MCP
• Run scanner from agent — sonar_run_analysis without leaving the chat
• Source coverage highlights — mark untested lines in source view
• Aggregated summary — single-call project health
• Array parameter support — pass severities/types as arrays or strings
• Zero Docker, zero JVM — Node.js, starts in ~0.1s

vs Official mcp/sonarqube

Choose official if you need inline code analysis, IDE integration, or run on Cloud/Enterprise. Choose ours if you're on Community Edition, want zero-overhead startup, or need the unique tools above.

Compatibility

Works with all SonarQube editions. sonar_list_pull_requests requires Developer Edition+.