SonarQube MCP Setup: Pin the Image, Scope the Token, and Start Read-Only
Run SonarSource’s official MCP server from a pinned container or a Java 21+ JAR. Use a short-lived user token, one project boundary, and read-only mode first. Verify issue and quality-gate reads before enabling analysis or broader actions, then keep the runtime, region, version, and permissions explicit.
Run SonarSource’s official MCP server from a pinned container or a Java 21+ JAR. Use a short-lived user token, one project boundary, and read-only mode first. Verify issue and quality-gate reads before enabling analysis or broader actions, then keep the runtime, region, version, and permissions explicit.
Table of contents
- Should you use the container, JAR, or hosted option?
- How do you configure Cloud, US region, or Server?
- How do you keep the token out of config and history?
- How do you verify issues and quality gates read-first?
- How do you limit projects, toolsets, and workspace access?
- How do you fix versions, stale images, regions, tokens, and missing tools?
- FAQ
Should you use the container, JAR, or hosted option?
Use the official sonarsource/sonarqube-mcp container when you want a repeatable runtime, or use the supported Java 21+ JAR when Docker is not part of your environment. Treat SonarQube Cloud as the hosted choice only after confirming its region and required variables. The official repository and documentation define the supported server paths and configuration model. SonarQube MCP repository · SonarQube MCP documentation
| Situation | Preferred path | First control |
|---|---|---|
| Container-based client setup | Official container | Pin the image reference |
| No Docker or container runtime | Java 21+ JAR | Confirm Java 21 or newer |
| SonarQube Cloud | Hosted endpoint | Set organization and region correctly |
| SonarQube Server | Managed instance | Confirm supported server version |
A pinned container gives you a known image choice for repeatable client configuration. A JAR gives you the supported non-Docker path, but it still needs a compatible Java runtime. In either case, begin with read-only behavior and a single project key.
Do not start by granting every available tool. First establish that the client can authenticate and read the expected project’s issues and quality-gate status. If those checks work, expand only when a specific workflow requires it.
How do you configure Cloud, US region, or Server?
For SonarQube Cloud, provide SONARQUBE_TOKEN and SONARQUBE_ORG; for SonarQube Server, provide SONARQUBE_TOKEN and SONARQUBE_URL. If the Cloud organization is in the United States region, use https://sonarqube.us as the Cloud endpoint. SonarQube MCP documentation
Keep the deployment type explicit:
- Identify whether the target is Cloud or Server.
- For Cloud, set the organization value and select the correct region.
- For US Cloud, use
https://sonarqube.us. - For Server, set the full server URL.
- Use a project key to keep the first connection scoped.
Server compatibility matters. SonarQube Server must be 2025.1 or newer, and Community Build must be 25.1 or newer. A correct token cannot compensate for an unsupported server version.
The same client configuration can therefore fail for different reasons: a missing organization value on Cloud, a missing URL on Server, a wrong Cloud region, or an older server. Record the deployment type and endpoint next to the client configuration so the intended target remains visible during troubleshooting.
How do you keep the token out of config and history?
Keep the token in the client’s secret or environment-variable mechanism, expose it to the MCP process at runtime, and avoid placing the literal value in saved configuration, shell history, tickets, or copied examples. Use a short-lived user token with only the access needed for the selected project. SonarQube token guidance
The required variable is SONARQUBE_TOKEN. Cloud also requires SONARQUBE_ORG; Server requires SONARQUBE_URL. Treat these names as configuration references, not values to paste into documentation.
A practical setup sequence is:
- Create or select a short-lived user token.
- Store it in the secret facility used by the MCP client.
- Pass the variable to the server process at runtime.
- Confirm the client configuration contains the variable name rather than the token.
- Revoke and replace the token when its intended task ends or its exposure is suspected.
Avoid testing by pasting a token into a command that may be retained in history. Also avoid sharing complete environment dumps in issue reports. If the client cannot reference secrets safely, pause at configuration review rather than broadening permissions.
How do you verify issues and quality gates read-first?
Verify two read paths before enabling analysis or broader actions: retrieve issues for the selected project, then retrieve its quality-gate status. These checks confirm the endpoint, organization or server URL, token, project boundary, and basic tool exposure in one small workflow.
Use a project key that you already intend to authorize. The first successful result should be recognizable: the returned issues belong to that project, and the quality-gate result belongs to the same project rather than an adjacent organization or instance.
Read-only mode is the correct initial posture. The official generator supports a read-only mode, so use it while checking connectivity and tool behavior. SonarQube MCP generator
If issue reads fail, check the endpoint, region, token, and project key before changing tool access. If quality-gate reads fail while issue reads work, check whether the selected project and token have the necessary visibility. Keep each change isolated so you know which correction resolved the failure.
After both reads succeed, document the exact project boundary and the enabled toolset. Only then consider analysis or other actions, and only when the workflow requires them.
How do you limit projects, toolsets, and workspace access?
Limit the connection to one default project key, select only the toolsets needed for the task, keep read-only mode enabled initially, and leave workspace mounting disabled unless advanced code analysis requires it. The official generator supports toolsets, read-only mode, a default project key, and an optional workspace mount. SonarQube MCP generator
Use these controls in order:
- Choose the project boundary first.
- Select the smallest toolset that covers issue and quality-gate reads.
- Enable read-only mode for initial setup.
- Add analysis-related tools only for a defined need.
- Mount a workspace only when advanced code analysis requires local code access.
A workspace mount changes what the MCP server can inspect locally, so treat it as a separate permission decision from SonarQube access. Keep the mounted path limited to the relevant workspace and avoid making unrelated directories available.
For a client-specific walkthrough, use the Cursor MCP client guide. For configuration checks, the MCPtrove config validator can be the next practical step. MCP’s architecture separates hosts, clients, and servers, so keep the SonarQube server’s permissions and the client’s local workspace permissions distinct. MCP architecture
How do you fix versions, stale images, regions, tokens, and missing tools?
Fix failures by checking one layer at a time: runtime version, image or JAR selection, deployment type, endpoint, required variable, token, project key, and enabled toolset. Do not solve a configuration mismatch by disabling authentication, TLS, or permission checks.
| Symptom | Check first | Corrective direction |
|---|---|---|
| Server will not start | Container reference or Java version | Use the official container or Java 21+ JAR |
| Cloud authentication fails | SONARQUBE_ORG and region | Confirm the organization and use https://sonarqube.us for US Cloud |
| Server connection fails | SONARQUBE_URL and Server version | Confirm the URL and supported version |
| Reads return no expected data | Project key and token scope | Recheck the one-project boundary and token |
| Expected tools are absent | Selected toolsets or read-only mode | Review generator selections before expanding access |
| Behavior differs after an update | Pinned image or JAR choice | Reconfirm the version used by the client |
A stale image can leave you debugging old behavior, while an unsupported Server version can look like a credential problem. Confirm the actual runtime and target before rotating credentials repeatedly.
If the endpoint is correct but the client lacks a tool, review the generator’s toolset selection. If a tool is present but cannot perform a write, confirm that read-only mode is intentional before changing it. Keep a small record of the runtime, endpoint type, project key, and selected toolsets.
For the security rationale behind token scope, read-only starts, and permission boundaries, see MCP security: what actually matters. Once the basic setup is clear, browse MCPtrove’s SonarQube MCP server directory entry for the next configuration reference.