SonarQube MCP Server Cursor IDE Setup 2026
SonarQube MCP server Cursor IDE setup 2026: run the official sonarsource/sonarqube-mcp Docker image for SonarQube Cloud or Server, the exact mcp.json, user-token rules, toolsets and read-only mode, the workspace mount that keeps file contents out of context, and fixes for the errors you will hit.
How do you connect SonarQube to Cursor with MCP? Add SonarSource's official server, which runs as the Docker image sonarsource/sonarqube-mcp, to ~/.cursor/mcp.json (or .cursor/mcp.json in a repo) with a stdio docker run command. For SonarQube Cloud it needs a SONARQUBE_TOKEN and usually your SONARQUBE_ORG; for a self-hosted SonarQube Server it needs a user token and SONARQUBE_URL. Once it is green under Settings > Tools & MCP, Cursor's agent can read your issues, Quality Gate status, security hotspots, coverage and rules, and can analyze code before you push it.
The official README also has an Install in Cursor button for each case. It writes the same Docker config with placeholder values, so you still have to paste in a real token afterward. The rest of this guide covers what the button does not: which token type works, how to keep the token out of your repo, how to trim the tool list, and what the startup errors mean.
New to MCP? Start with what the Model Context Protocol is, then come back.
What the SonarQube MCP server gives Cursor
SonarSource describes it as an MCP server that "enables seamless integration with SonarQube Server or Cloud for code quality and security," including analysis of code snippets inside the agent context. In practice, it turns questions you would normally answer by clicking around the SonarQube UI into tool calls the agent can make while it edits:
src/payments."java:S2095 and fix every instance in this file."The server talks to the SonarQube Web API with your token. It sees what your account can see, nothing more. If you cannot browse a project in the UI, the agent cannot read it either.
The tools that matter most
The full list is long and grows with each release. These are the ones you will use day to day, by name as the README lists them:
| Tool | What it does |
|---|---|
search_my_sonarqube_projects | Finds projects (and their keys) your token can see |
list_organizations | Lists SonarQube Cloud organizations you belong to |
search_sonar_issues_in_projects | Searches issues across your projects, with filters |
change_sonar_issue_status | Marks an issue accepted or false positive, or reopens it |
get_project_quality_gate_status | Returns the Quality Gate result for a project, branch or PR |
show_rule | Full details for a rule, including the reasoning and examples |
search_security_hotspots / show_security_hotspot | Finds and opens security hotspots |
change_security_hotspot_status | Reviews a hotspot (needs a resolution when marking reviewed) |
get_component_measures | Pulls metrics such as coverage or duplication for a project, folder or file |
search_files_by_coverage / get_file_coverage_details | Worst-covered files, then the uncovered lines in one file |
get_duplications | Duplicated blocks for a file |
analyze_code_snippet | Runs SonarQube analyzers on code you hand it |
list_branches / list_pull_requests | Discovers branch names and PR keys for branch or PR analysis |
There are more groups: dependency risks (which need SonarQube Advanced Security), portfolios and enterprises, webhooks, system health for Server admins, and newer code-context and architecture tools on entitled organizations. Most people never need those in an editor.
Before you start
~/.cursor/mcp.json; project config is .cursor/mcp.json in the repo root. See the Cursor MCP setup guide if this is your first server.Step 1: Create the right kind of token
This is where most broken setups start.
SonarQube Cloud: generate a token from your account's security settings. A personal token is what the server expects. Note your organization key too; you can find it in your organization settings or the URL of your org page.
SonarQube Server: generate a token of type User. The README is blunt about this: connection to SonarQube Server "requires a token of type USER and will not function properly if project tokens or global tokens are used." A project analysis token is the one your CI pipeline already has, which is exactly why people grab it and then wonder why half the tools fail.
Give the token the narrowest account that still sees the projects you care about. Anything the agent does, it does as that user.
Step 2: Add the server to mcp.json
SonarQube Cloud
{
"mcpServers": {
"sonarqube": {
"command": "docker",
"args": [
"run", "--init", "--pull=always", "-i", "--rm",
"-e", "SONARQUBE_TOKEN",
"-e", "SONARQUBE_ORG",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "${env:SONARQUBE_TOKEN}",
"SONARQUBE_ORG": "your-org-key"
}
}
}
}
On SonarQube Cloud, only the token is strictly required. Setting SONARQUBE_ORG fixes the organization so the agent never has to guess; leave it out if you work across several orgs and want the agent to call list_organizations first. For SonarQube Cloud US, add "SONARQUBE_URL": "https://sonarqube.us" to env and "-e", "SONARQUBE_URL" to args.
SonarQube Server (self-hosted)
{
"mcpServers": {
"sonarqube": {
"command": "docker",
"args": [
"run", "--init", "--pull=always", "-i", "--rm",
"-e", "SONARQUBE_TOKEN",
"-e", "SONARQUBE_URL",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "${env:SONARQUBE_USER_TOKEN}",
"SONARQUBE_URL": "https://sonarqube.example.com"
}
}
}
}
Two details in both configs are easy to get wrong:
1. The -e NAME flags have no value. They tell Docker to pass the variable through from the environment Cursor sets from the env block. If you delete them, the container starts without a token.
2. The token comes from your shell, not the file. Cursor resolves ${env:NAME} in command, args, env, url and headers, so "${env:SONARQUBE_TOKEN}" reads the token from your environment. That makes the project-level .cursor/mcp.json safe to commit. SonarSource's own security notes say never to commit tokens and to prefer environment variable substitution. If you launch Cursor from the Dock or Start menu, make sure the variable is set somewhere the app actually inherits, such as your login shell profile, then restart Cursor.
Save the file, open Settings > Tools & MCP, and toggle sonarqube on. The first start takes longer while Docker pulls the image.
Pin the version if you need reproducibility
--pull=always with the bare image name means you get the newest release every time Cursor starts the server. That is convenient on a laptop. For a team config, SonarSource suggests pinning a tag such as sonarsource/sonarqube-mcp:<version> and dropping --pull=always so Docker does not upgrade silently. Tags are listed on Docker Hub.
Step 3: Keep file contents out of the context window
By default, analyze_code_snippet expects the agent to paste the whole file into the tool call. On a big file, that is a lot of tokens per call. The README's fix is to mount your project into the container at /app/mcp-workspace; when the mount is present, the server reads files from disk by project-relative path instead.
In a project-level .cursor/mcp.json, Cursor's ${workspaceFolder} variable makes that portable:
"args": [
"run", "--init", "--pull=always", "-i", "--rm",
"-e", "SONARQUBE_TOKEN",
"-e", "SONARQUBE_ORG",
"-v", "${workspaceFolder}:/app/mcp-workspace",
"sonarsource/sonarqube-mcp"
]
${workspaceFolder} resolves to the folder that contains .cursor/mcp.json. On Windows, Docker Desktop needs that drive shared; if the mount fails, try the path with forward slashes.
Step 4: Trim the tools and decide on write access
Every enabled tool's name, description and schema is loaded into the agent's context in every conversation. SonarSource added two switches for that:
SONARQUBE_TOOLSETS: a comma-separated list of toolsets to enable. If unset, a default set of "important" toolsets loads, including issues, projects, quality gates, rules, measures, duplications, security hotspots, coverage and analysis. The projects toolset is always on because other tools need project keys.SONARQUBE_READ_ONLY: set to true to disable every write operation, such as changing an issue or hotspot status.A tight, read-only setup for "help me fix what Sonar flagged" looks like this:
"env": {
"SONARQUBE_TOKEN": "${env:SONARQUBE_TOKEN}",
"SONARQUBE_ORG": "your-org-key",
"SONARQUBE_TOOLSETS": "issues,quality-gates,rules,measures",
"SONARQUBE_READ_ONLY": "true"
}
Remember to add "-e", "SONARQUBE_TOOLSETS" and "-e", "SONARQUBE_READ_ONLY" to args too, or the container never sees them. If you work on a single project, SONARQUBE_PROJECT_KEY removes the projectKey parameter from every tool so the agent cannot point at the wrong one.
Read-only is the sensible default for a shared config. Marking issues as false positives from an agent is useful, but it is a change other people will see in SonarQube, and an agent that is trying to make a Quality Gate pass has an obvious incentive to do exactly that. Turn writes on deliberately, for people who will check what was changed. Our MCP security best practices cover the general case.
Step 5: Check it works
In Cursor's agent chat, try:
1. "Use SonarQube to list my projects." The agent should call search_my_sonarqube_projects and return keys.
2. "What is the Quality Gate status of <project-key> on main?"
3. "Show the critical issues in <project-key> and explain the top one with show_rule."
If the agent answers from memory instead of calling a tool, say "use the sonarqube MCP tools" once, or add a short project rule telling the agent to check SonarQube before claiming a file is clean.
Optional: pair it with SonarQube for IDE
If you already run the SonarQube for IDE extension, the MCP server can talk to it. Set SONARQUBE_IDE_PORT to the extension's port (the README gives the range 64120 to 64130) and pass it through with -e. On Linux, the container cannot reach the extension's localhost server unless you add --network=host to the docker run arguments.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Server exits with "SonarQube server version is not supported" | Instance older than SQS 2025.1 or Community Build 25.1 | Upgrade SonarQube Server; there is no flag to bypass the check |
| Tools load but return permission errors on Server | Project or global token instead of a user token | Generate a User token and replace it |
| Red dot in Tools & MCP, no log output | Docker not running, or docker not on Cursor's PATH | Start Docker Desktop; use the full path to docker in command if needed |
| Connects to Cloud when you meant your Server | SONARQUBE_URL missing, so the token defaults to Cloud | Add SONARQUBE_URL to env and -e SONARQUBE_URL to args |
| Agent asks which organization to use every time | SONARQUBE_ORG not set on Cloud | Set it, or let the agent call list_organizations once |
| A tool from the README is missing | Old cached image, or its toolset is not enabled | docker pull sonarsource/sonarqube-mcp, restart Cursor, check SONARQUBE_TOOLSETS |
| Token works in curl but not in Cursor | ${env:...} variable not visible to the Cursor app | Set it in your login shell profile and fully restart Cursor |
For more detail, the server writes logs to STORAGE_PATH/logs/mcp.log; in the container image STORAGE_PATH is set for you. SONARQUBE_DEBUG_ENABLED=true adds debug output to the log and stderr. Our general MCP debugging guide covers reading Cursor's MCP output panel.
Running it for a team over HTTP
The stdio setup above starts one container per Cursor window, which is right for most people. The server also supports Streamable HTTP (SONARQUBE_TRANSPORT=http or https), where one long-running instance serves several clients and each request carries its own token in an Authorization: Bearer header. SonarSource recommends HTTPS for multi-user deployments, and the server binds to localhost by default. Clients can narrow toolsets and force read-only per request with headers, but they cannot enable more than the server was started with. SonarSource also runs a hosted SonarQube Cloud MCP service that supports OAuth sign-in; self-hosted Server still uses tokens.
Frequently asked questions
Is there an official SonarQube MCP server?
Yes. SonarSource publishes it on GitHub as SonarSource/sonarqube-mcp-server and ships it as the Docker image sonarsource/sonarqube-mcp. It works with both SonarQube Cloud and self-hosted SonarQube Server.
Does the SonarQube MCP server work with SonarQube Community Build?
Yes, if the instance is Community Build 25.1 or later. The server checks the version at startup and refuses to run against older releases. Some tool groups, such as dependency risks, need paid editions or add-ons.
What token does the SonarQube MCP server need?
For SonarQube Server, a token of type User; project and global analysis tokens will not work properly. For SonarQube Cloud, a personal token from your account's security settings, usually with your organization key in SONARQUBE_ORG.
Can I stop the agent from changing issue status in SonarQube?
Yes. Set SONARQUBE_READ_ONLY to true and pass it into the container. That disables write tools such as changing an issue or security hotspot status. You can also limit the loaded tools with SONARQUBE_TOOLSETS.
Do I have to use Docker?
Docker or another OCI-compatible runtime such as Podman is the recommended route. SonarSource also documents running a pre-built standalone JAR from its binaries repository, which needs a Java runtime and a writable STORAGE_PATH you set yourself.
Related Guides
Sources: SonarSource/sonarqube-mcp-server README, sonarsource/sonarqube-mcp on Docker Hub, SonarQube Server token docs, Cursor MCP documentation. Checked November 12, 2026.