Guides · Cursor

How to connect the SonarQube MCP server to Cursor

The SonarQube MCP Server lets Cursor's agent 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 Cursor starts it as a local stdio server through Docker, and it acts with the rights of the token you give it.

Steps summarize the official docs linked below, checked 2026-11-02. Client UIs change; if a menu name differs, the linked docs win.

1. Check what you need
Docker (or another OCI runtime such as Podman) on the machine running Cursor, available on your PATH. For SonarQube Cloud: a token (SONARQUBE_TOKEN) and your organization key (SONARQUBE_ORG); 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.
2. Quick start: the Add to Cursor link, then move the token out
SonarSource's README has two Add to Cursor buttons, one for SonarQube Cloud and one for SonarQube Server. They install a server named sonarqube that runs docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp (or -e SONARQUBE_URL for Server), with placeholder values such as YOUR_TOKEN in env. Don't paste the real token over the placeholder: replace it with ${env:SONARQUBE_TOKEN} as in the next step, so the secret never sits in mcp.json. For Cloud US, add "SONARQUBE_URL": "https://sonarqube.us" to env and -e SONARQUBE_URL to the docker arguments.

3. Manual: SonarQube Cloud in mcp.json, read-only, token from your environment

This is the Cloud config from SonarSource's README with SONARQUBE_READ_ONLY=true added, which turns off every write tool (such as changing an issue's status), and with the values read through Cursor's ${env:NAME} interpolation, which works in command, args and env. Use ~/.cursor/mcp.json to have it in every project, or .cursor/mcp.json to share it with the repository; each teammate then sets their own variables. Leave the read-only line out only if you want the agent to accept issues or mark them false positives.

# once, in your shell profile or secret manager:
export SONARQUBE_TOKEN="YOUR_TOKEN"
export SONARQUBE_ORG="your-org-key"

# ~/.cursor/mcp.json or .cursor/mcp.json:
{
  "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": "${env:SONARQUBE_TOKEN}",
        "SONARQUBE_ORG": "${env:SONARQUBE_ORG}",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

4. Or SonarQube Server

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

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

5. Or load the values from a .env file

Because this is a stdio server, Cursor also accepts envFile, a path to an environment file it loads for the server. Point it at a file that is in your .gitignore and drop the matching ${env:...} entries from env. envFile is only available for stdio servers, not remote ones.

{
  "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"
      ],
      "envFile": "${workspaceFolder}/.env.sonarqube",
      "env": {
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

6. Load only the toolsets you use and mount the project
Every enabled tool's name, description and schema is loaded into the agent's context in every conversation. SONARQUBE_TOOLSETS limits the server to the toolsets you list (projects is always on), and SONARQUBE_PROJECT_KEY fixes one project so its key is removed from the tool schemas. Mounting the project at /app/mcp-workspace lets analysis tools read files from disk instead of receiving whole files through the agent's context; Cursor resolves ${workspaceFolder} in args to the folder that holds .cursor/mcp.json. Add each variable to env and a matching -e flag to args.
```
# add to "env":
"SONARQUBE_TOOLSETS": "issues,quality-gates,security-hotspots,measures",
"SONARQUBE_PROJECT_KEY": "my-project"

# add to "args", before the image name:
"-e", "SONARQUBE_TOOLSETS", "-e", "SONARQUBE_PROJECT_KEY",
"-v", "${workspaceFolder}:/app/mcp-workspace"
```
7. Check that it works
Restart Cursor (or toggle the server in Customize) after editing mcp.json; the SonarQube tools then appear under Available Tools. Ask about a project in plain language; these prompts are from SonarSource's examples. If it doesn't connect, open the Output panel (Cmd+Shift+U) and select MCP Logs.
```
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?
```
8. Keep tool calls behind approval
Cursor asks for approval before running MCP tools by default, and MCP tools follow the same Run Modes as terminal commands. If you skipped read-only mode, don't add SonarQube's write tools to an allowlist unless you're fine with the agent changing issue status on its own. Team admins can also approve the docker command and restrict which SonarQube tools run automatically from the MCP Allowlist in the Cursor dashboard.

Good to know

The server sends anonymous usage data to SonarSource (no source code or IP address, per the README). Add "TELEMETRY_DISABLED": "true" to env and -e TELEMETRY_DISABLED to args to turn it off.
--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.
Cloud Agents keep their own MCP sign-ins on Cursor's servers, separate from the ones on your machine; this guide covers the local Cursor IDE setup.
The license is SonarSource's source-available license (SONAR Source-Available License v1.0), not an OSI open-source license.

Troubleshooting

Only errors documented in the official docs; each fix links to its source.

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. source ↗
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 Cursor. source ↗
The server fails to start and MCP Logs mention docker: Cursor's command must be on your system PATH or be a full path. Use the full path to docker if Cursor was launched without your shell's PATH, and check that the Docker daemon is running. source ↗
Authentication errors even though the token is set: ${env:SONARQUBE_TOKEN} is read from the environment Cursor runs in. Set the variable in your shell profile or system environment, restart Cursor, and check the -e SONARQUBE_TOKEN flag is still in args so Docker passes it into the container. source ↗
Connection or configuration problems you can't see: Set SONARQUBE_DEBUG_ENABLED=true (in env, plus -e SONARQUBE_DEBUG_ENABLED in args) for debug logs on stderr, which show up in Cursor's MCP Logs, and in STORAGE_PATH/logs/mcp.log. source ↗
On Linux, the container can't reach SonarQube for IDE: A container can't reach the SonarQube for IDE server on localhost. Add --network=host to the docker run arguments. source ↗

Sources

Catalog verdict

From the AgentTask Atlas catalog entry (verified 2026-10-26). Based on official docs, not hands-on tested. New to MCP in Cursor? Start with the general How to add an MCP server to Cursor.

SonarQube MCP Server · SonarSource · needs credentials
Pick it if your project already runs on SonarQube Cloud or Server and you want the agent to read issues and quality gates during review; set SONARQUBE_READ_ONLY=true for review-only use.

Ask the catalog from inside Cursor: the AgentTask Atlas MCP server is free, read-only and needs no account.

Compare by task: Databases & SQL · Git & GitHub repos · Code review · CI/CD · Infra & deploy · Debugging & observability · Library docs & research · Web fetching & scraping · Frontend & UI · Local files · Docs & writing · Build AI apps · Planning & reasoning · Utilities

Same server in other clients: How to connect the SonarQube MCP server to Claude Code

⚠ No independent security audit: entries summarize official sources only. Review permissions and code before installing.

How to connect the SonarQube MCP server to Cursor

1. Check what you need

2. Quick start: the Add to Cursor link, then move the token out