Skip to main content
← Back to Articles
mcpcursorsonarqubesonarcloudcode-qualitysecuritydockersetup2026

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.

By Web MCP Guide•November 12, 2026•14 min read

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:

  • "Is the Quality Gate failing on this branch, and why?"

  • "List the blocker and critical issues in src/payments."

  • "Explain rule java:S2095 and fix every instance in this file."

  • "Which files have the worst coverage?"

  • "Show the open security hotspots and mark the false positive as reviewed."
  • 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:

    ToolWhat it does
    search_my_sonarqube_projectsFinds projects (and their keys) your token can see
    list_organizationsLists SonarQube Cloud organizations you belong to
    search_sonar_issues_in_projectsSearches issues across your projects, with filters
    change_sonar_issue_statusMarks an issue accepted or false positive, or reopens it
    get_project_quality_gate_statusReturns the Quality Gate result for a project, branch or PR
    show_ruleFull details for a rule, including the reasoning and examples
    search_security_hotspots / show_security_hotspotFinds and opens security hotspots
    change_security_hotspot_statusReviews a hotspot (needs a resolution when marking reviewed)
    get_component_measuresPulls metrics such as coverage or duplication for a project, folder or file
    search_files_by_coverage / get_file_coverage_detailsWorst-covered files, then the uncovered lines in one file
    get_duplicationsDuplicated blocks for a file
    analyze_code_snippetRuns SonarQube analyzers on code you hand it
    list_branches / list_pull_requestsDiscovers 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


  • Docker, or another OCI runtime. The recommended path is the container image. Docker Desktop on macOS or Windows works, as does Docker Engine on Linux. SonarSource notes that Podman or nerdctl work if you swap the command name. If you have never run an MCP server in a container, our Docker MCP setup guide covers the basics.

  • A recent Cursor build. MCP servers live under Settings > Tools & MCP. Global config is ~/.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.

  • A SonarQube account with at least one analyzed project. The server reads results; it does not create your first analysis from nothing.

  • For SonarQube Server: version 2025.1 or later (or Community Build 25.1 or later). The MCP server checks the version at startup and exits if the instance is older.
  • 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

    SymptomLikely causeFix
    Server exits with "SonarQube server version is not supported"Instance older than SQS 2025.1 or Community Build 25.1Upgrade SonarQube Server; there is no flag to bypass the check
    Tools load but return permission errors on ServerProject or global token instead of a user tokenGenerate a User token and replace it
    Red dot in Tools & MCP, no log outputDocker not running, or docker not on Cursor's PATHStart Docker Desktop; use the full path to docker in command if needed
    Connects to Cloud when you meant your ServerSONARQUBE_URL missing, so the token defaults to CloudAdd SONARQUBE_URL to env and -e SONARQUBE_URL to args
    Agent asks which organization to use every timeSONARQUBE_ORG not set on CloudSet it, or let the agent call list_organizations once
    A tool from the README is missingOld cached image, or its toolset is not enableddocker pull sonarsource/sonarqube-mcp, restart Cursor, check SONARQUBE_TOOLSETS
    Token works in curl but not in Cursor${env:...} variable not visible to the Cursor appSet 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


  • Sentry MCP Server Cursor IDE Setup (2026)

  • GitHub MCP Server Cursor IDE Setup (2026)

  • Docker MCP Server Setup Guide (2026)

  • MCP Security Best Practices (2026)
  • Sources: SonarSource/sonarqube-mcp-server README, sonarsource/sonarqube-mcp on Docker Hub, SonarQube Server token docs, Cursor MCP documentation. Checked November 12, 2026.




    Related guides