SonarQube MCP in Claude Code: read-only setup, keeping the token out of your repo, and fewer toolsets

The SonarQube MCP Server lets Claude Code read issues, quality gates, measures, security hotspots and coverage from SonarQube Cloud or SonarQube Server. SonarSource ships it as the sonarsource/sonarqube-mcp container image, so Claude Code starts it as a local stdio process through Docker, and it acts with the rights of the token you give it.

The steps below summarize the official docs (the SonarQube MCP Server README, SonarSource's configuration generator, the SonarQube Cloud docs on managing tokens, and the Claude Code docs on MCP and permissions), checked on 2026-10-28. They are based on the official docs, not hands-on tested; if something differs on your version, the linked docs win. The original version of this guide lives at AgentTask Atlas: How to connect the SonarQube MCP server to Claude Code.

1. Check what you need

Docker on the machine running Claude Code. For SonarQube Cloud: a token (SONARQUBE_TOKEN); SONARQUBE_ORG is optional and fixes the organization, and Cloud US also needs SONARQUBE_URL=https://sonarqube.us. For SonarQube Server: a USER token plus SONARQUBE_URL; the server must be SonarQube Server 2025.1 or Community Build 25.1 or newer. SonarSource also has an official configuration generator at mcp.sonarqube.com/config-generator.html if you'd rather not write the command yourself.

2. Add it for SonarQube Cloud, read-only

export SONAR_TOKEN="YOUR_TOKEN"   # better: load it from your secret manager or shell profile
export SONAR_ORG="your-org-key"
claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  --env SONARQUBE_ORG=$SONAR_ORG \
  --env SONARQUBE_READ_ONLY=true \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG -e SONARQUBE_READ_ONLY sonarsource/sonarqube-mcp

This is the Claude Code command from SonarSource's README with SONARQUBE_READ_ONLY=true added, which turns off every write tool (such as changing an issue's status). Leave that line out only if you want the agent to accept issues or mark them false positives. Claude Code writes to local scope by default (only you, only this project, stored in ~/.claude.json outside your repository); add --scope user to make it available in all your projects, or --scope project to write it to .mcp.json (see step 4 before doing that). Everything after -- is the docker command Claude Code runs, untouched.

3. Or add it for SonarQube Server

Same command, with your server's URL instead of the organization. Use a USER token, not a project or global analysis token.

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  --env SONARQUBE_URL=$SONAR_URL \
  --env SONARQUBE_READ_ONLY=true \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL -e SONARQUBE_READ_ONLY sonarsource/sonarqube-mcp

4. Share it with the team in .mcp.json without committing the token

Claude Code expands ${VAR} in a project .mcp.json's command, args and env, so each teammate sets SONARQUBE_TOKEN and SONARQUBE_ORG in their own shell and the file stays secret-free:

{
  "mcpServers": {
    "sonarqube": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "-e", "SONARQUBE_READ_ONLY", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "${SONARQUBE_TOKEN}",
        "SONARQUBE_ORG": "${SONARQUBE_ORG}",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

Claude Code asks each person to approve project-scoped servers the first time.

5. Load only the toolsets you use

Every enabled tool's name, description and schema sits in Claude Code's context in every session. SONARQUBE_TOOLSETS limits the server to the toolsets you list (projects is always on), and SONARQUBE_PROJECT_KEY fixes one project so tools stop asking for it. Pass each one with another --env and -e pair, or in the env block above.

--env SONARQUBE_TOOLSETS=issues,quality-gates,security-hotspots,measures
--env SONARQUBE_PROJECT_KEY=my-project
# and add to the docker args:
-e SONARQUBE_TOOLSETS -e SONARQUBE_PROJECT_KEY

6. Check the connection and try it

claude mcp list
claude mcp get sonarqube
# in a session:
My quality gate is failing for my project. Can you help me understand why and fix the most critical issues?
I want to reduce technical debt in my project. What are the top issues I should prioritize?

claude mcp list should show sonarqube as connected, and /mcp shows its tools. The prompts above are from SonarSource's examples.

7. Keep write tools behind a prompt

If you skipped read-only mode, an ask rule in .claude/settings.json makes Claude Code confirm every SonarQube tool call before it runs, including status changes:

{
  "permissions": { "ask": ["mcp__sonarqube__*"] }
}

Don't add an allow rule for mcp__sonarqube__* unless you are fine with the agent accepting issues or marking them false positives on its own.

Troubleshooting (from the official docs)

• "SonarQube server version is not supported, minimal version is SQS 2025.1 or SQCB 25.1": the server checks your SonarQube Server version at startup. Upgrade to a supported release; this check doesn't apply to SonarQube Cloud.
• A feature or tool from the README is missing: you are probably on an old cached image. Run docker pull sonarsource/sonarqube-mcp (or keep --pull=always), then restart Claude Code.
• Connection or configuration problems you can't see: set SONARQUBE_DEBUG_ENABLED=true for debug logs on stderr and in STORAGE_PATH/logs/mcp.log.
• The server times out while starting: raise Claude Code's MCP startup timeout, for example MCP_TIMEOUT=10000 claude for 10 seconds. Running docker pull sonarsource/sonarqube-mcp beforehand also keeps the image download out of startup.
• claude mcp list shows sonarqube as ⏸ Pending approval: it comes from a project .mcp.json you haven't approved yet. Run claude interactively in the project, accept the workspace trust dialog and approve the server.
• claude mcp list warns about a missing environment variable: a ${VAR} in .mcp.json names a variable that isn't set, so Claude Code passes the literal ${VAR} text. Export SONARQUBE_TOKEN (and SONARQUBE_ORG or SONARQUBE_URL) in the shell you start claude from.

Notes

• The server sends anonymous usage data to SonarSource (no source code or IP address, per the README). Add --env TELEMETRY_DISABLED=true and -e TELEMETRY_DISABLED to turn it off.
• analyze_code_snippet otherwise receives whole files as arguments. Mounting your project at /app/mcp-workspace (-v /path/to/project:/app/mcp-workspace in the docker args) lets it read files from disk instead, so file contents don't pass through the agent's context.
• --pull=always gets updates automatically. For reproducible setups, pin a tag such as sonarsource/sonarqube-mcp:<version> and drop --pull=always so Docker doesn't upgrade silently.
• Give the agent a token with only the rights it needs: the server can do whatever that token can.
• The license is SonarSource's source-available license (SONAR Source-Available License v1.0), not an OSI open-source license.