Quickstart guide

This page lays out the process of getting your SonarQube MCP Server up and running in the most simple way possible. Three different user configurations are outlined below.

We've prepared three user guides to help get you going with the SonarQube MCP Server in the fastest way possible. Each guide is designed for a different configuration that should fit most user's requirements. If you're having troubles with a unique configuration (or for any reason, really), check out the Help page to get in touch with us, or review the Troubleshooting page for some common issues experiened by other users.

General user guide

The General user guide is designed for users who are operating independently and need a quick setup designed around your specific IDE or CLI.

Check your Prerequisites

Review the Prerequisites and make sure that you’ve got everything you need to get going.

Gather your variables

You will need a few Common variables to authenticate your server.

If you’re using SonarQube Cloud, retrieve your token and organization name.
For SonarQube Server and SonarQube Community Build, retrieve your user token and server URL.

Find your IDE or CLI and connect

Have a look at the MCP Server setup in your IDE instructions below. Find your IDE or CLI in the list and adjust the code samples using your variables. The Stdio transport mode will be deployed.

Start using the MCP tools

Check out the Tools to get going using the server while you code.

Configuration guide

The Configuration guide is designed for setting up a central server that multiple users will

Check your deployment

Depending on how you want to deploy the server, you might If you need a unique configuration. First, figure out which Transport mode you want to use, then grab the correct Environment variables you'll need.

Deploy your server

Using the Environment variables you grabbed in step 1, deploy your SonarQube MCP Server using the Transport mode you want to use.

Find your IDE or CLI and connect

Have a look at the MCP Server setup in your IDE instructions below. Find your IDE or CLI in the list and adjust the code samples using your variables. Each user will connect to the server using their own Common variables.

Start using the MCP tools

Check out the Tools to get going using the server while you code.

Build your own server guide

The Build your own server guide is designed for users who need to either use the provided JAR file, or want to build their own from scratch.

Review your options

Our Docker image provides the easiest way to get going, but it's possible that it won't work for you. To build your MCP server locally, check out the instructions to Build locally.

Set up your installation

Because you're building your own server locally, you'll need to complete the setup with a Manual installation.

Start using the MCP tools

Finally, check out the Tools to get going using the server while you code.

MCP Server setup in your IDE

Launch the server with Docker

The SonarQube MCP Server can be launched in two ways: With a Docker container (recommended), or from a JAR file built locally. The full details about building your server is on the Build your SonarQube MCP Server page.

The recommended method is to rely on the official Docker image found on the mcp/sonarqube Docker Hub page, then follow the Quick configuration or Manual configuration instructions inside of each IDE/CLI expandable below.

IDE setup

The setup instructions below contain code samples for both SonarQube Cloud and SonarQube Server. If you're using SonarQube Community Build, use the code samples for SonarQube Server.

Setup with Claude Code

Here are the basic details to set up the SonarQube MCP Server in Claude Code. For full details on installing MCP Servers with Claude Code, refer to the official Anthropic docs.

With an HTTP transport server

Please see the Transport mode article for details and code samples.

As a local stdio server

The claude mcp add sonarqube command allows you to set up the SonarQube MCP Server as a local stdio server:

For SonarQube Cloud:

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=<YourSonarQubeToken> \
  --env SONARQUBE_ORG=<YourOrganizationName> \
  -- \
docker run \
  -i 
  --name sonarqube-mcp-server 
  --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG mcp/sonarqube
  -- \

For SonarQube Server:

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=<YourSonarQubeUserToken> \
  --env SONARQUBE_URL=<YourSonarQubeURL> \
  -- \
  docker run -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL mcp/sonarqube

User tokens are required when setting up connected mode or an MCP Server between SonarQube Server and SonarQube for IDE. Note that binding will not function properly if SonarQube Server project tokens or global tokens are used during the setup process.

Manual configuration

For a manual configuration, add this MCP configuration to your ~/.claude.json file.

Claude Code with SonarQube Cloud

{
  "mcpServers": {
    "sonarqube": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_ORG",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeToken>",
        "SONARQUBE_ORG": "<YourOrganizationName>"
      }
    }
  }
}

Claude Code with SonarQube Server

{
  "mcpServers": {
    "sonarqube": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeToken>",
        "SONARQUBE_URL": "<YourSonarQubeURL>"
      }
    }
  }
}

When finished with your setup, you can verify the MCP connection by running mcp__sonarqube__ping_system to test the connection.

Using the SonarQube MCP Server tools

When you're ready to engage with Claude Code, see the Tools page for a full list of available tools.

Setup with Codex CLI

In your ~/.codex/config.toml file, add the following configuration:

Codex CLI with SonarQube Cloud:

[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--name", "sonarqube-mcp-server", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "mcp/sonarqube"]
env = { "SONARQUBE_TOKEN" = "<YourSonarQubeToken>", "SONARQUBE_ORG" = "<YourOrganizationName>" }

Codex CLI with SonarQube Server:

[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--name", "sonarqube-mcp-server", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "mcp/sonarqube"]
env = { "SONARQUBE_TOKEN" = "<YourSonarQubeUserToken>", "SONARQUBE_URL" = "<YourSonarQubeURL>" }

Setup in Cursor

Automatic configuration

When you're using an AI-enabled IDE such as Cursor, Windsurf, or VS Code with Copilot enabled, and have already completed your Connected mode setup in SonarQube for IDE with SonarQube Server or SonarQube Cloud, a quick select button is available.

Select the icon, Configure MCP Server from the CONNECTED MODE view window to use your connected mode credentials to start using the SonarQube MCP Server. The same workflow is available in the AI AGENTS CONFIGURATION view.

Quick configuration

You can use the following link to quickly set up the SonarQube MCP Server in Cursor. This will generate a configuration file in Cursor and automatically fill it with your environment variables. Make sure your Quickstart guide are configured first.

Check out our YouTube demo to watch the Cursor & SonarQube MCP Server integration in action.

With an HTTP transport server

Please see the Transport mode article for details and code samples.

Manual configuration

For a manual configuration, add this MCP configuration to your mcp.json file, at the location specified in the Cursor documentation.

Cursor with SonarQube Cloud

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_ORG",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeToken>",
        "SONARQUBE_ORG": "<YourOrganizationName>"
      }
    }
  }
}

Cursor with SonarQube Server

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeUserToken>",
        "SONARQUBE_URL": "<YourSonarQubeURL>"
      },
    }
  }
}

For more information on the environment variables and how to retrieve the token and organization information, see the Quickstart guide article below.

Once you’ve set up the Sonar MCP Server, the configuration appears under Tools & Integrations in Cursor.

Using the SonarQube MCP Server tools

You can use the Cursor chat to use one of the available tools, for example, by typing: "search my sonarqube projects". See the Tools page for a full list of available tools.

Setup with Gemini CLI

Install the SonarQube MCP Server extension by using the following command:

gemini extensions install https://github.com/SonarSource/sonarqube-mcp-server

You will need to set the required environment variables before starting Gemini:

SONARQUBE_TOKEN="<YourSonarQubeUserToken>"
SONARQUBE_ORG="<YourOrganizationName>" // For SonarQube Cloud, empty otherwise
SONARQUBE_URL="<YourSonarQubeServerURL>" // For SonarQube Server, empty otherwise

Once installed, the extension will be found at: <Home>/.gemini/extensions/sonarqube-mcp-server/gemini-extension.json

Check out this video of Gemini CLI & SonarQube MCP Server for more insights.

Setup in VS Code with GitHub Copilot

To use the SonarQube MCP server in VS Code, you must first install Copilot Chat.

Automatic configuration

Select the icon, Configure MCP Server from the CONNECTED MODE view window to use your connected mode credentials to start using the SonarQube MCP Server. The same workflow is available in the AI AGENTS CONFIGURATION view.

Quick configuration

You can use the following link to quickly set up the SonarQube MCP Server in VS Code with GitHub Copilot. This will generate a configuration file in VS Code and automatically fill it with your environment variables. Make sure your environment variables (see section below) are configured first.

Connect to SonarQube Cloud

With an HTTP transport server

Please see the Transport mode article for details and code samples.

Manual configuration

Follow the VS Code instructions and add the SonarQube MCP Server to your .vscode/mcp.json file.

Copilot with SonarQube Cloud

{
  "mcp": {
    "servers": {
      "sonarqube": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--name",
          "sonarqube-mcp-server",
          "--rm",
          "-e",
          "SONARQUBE_TOKEN",
          "-e",
          "SONARQUBE_ORG",
          "mcp/sonarqube"
        ],
        "env": {
          "SONARQUBE_TOKEN": "<YourSonarQubeToken>",
          "SONARQUBE_ORG": "<YourOrganizationName>"
        }
      }
    }
  }
}

For more information on the environment variables and how to retrieve the token and organization information, see the Quickstart guide article below

Copilot with SonarQube Server

{
  "mcp": {
    "servers": {
      "sonarqube": {
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--name",
            "sonarqube-mcp-server",
            "--rm",
            "-e",
            "SONARQUBE_TOKEN",
            "-e",
            "SONARQUBE_URL",
            "mcp/sonarqube"
        ],
        "env": {
          "SONARQUBE_TOKEN": "<YourSonarQubeUserToken>",
          "SONARQUBE_URL": "<YourSonarQubeURL>"
    }
  }
}

Using the SonarQube MCP Server tools

Once you’ve set up the Sonar MCP Server in VS Code, you can use the tools it provides in agent mode. See the Tools page for a full list of available tools.

See also the VS Code documentation for more information about using MCP servers VS Code.

Setup with GitHub Copilot CLI

After starting Copilot CLI, run the following command to add the SonarQube MCP server:

/mcp add

You will have to provide specific information about your MCP server; use the tab key to navigate between fields.

GitHub Copilot CLI with SonarQube Cloud:

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --name, sonarqube-mcp-server, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, mcp/sonarqube
Environment Variables: SONARQUBE_TOKEN=<YourSonarQubeToken>,SONARQUBE_ORG=<YourOrganizationName>
Tools: *

GitHub Copilot CLI with SonarQube Server:

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --name, sonarqube-mcp-server, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, mcp/sonarqube
Environment Variables: SONARQUBE_TOKEN=<YourSonarQubeUserToken>,SONARQUBE_URL=<YourSonarQubeURL>
Tools: *

The configuration file is located at ~/.copilot/mcp-config.json.

Setup with GitHub Copilot coding agent

The GitHub Copilot coding agent can leverage the SonarQube MCP server directly in your CI/CD environment.

To add the secrets to your Copilot environment, follow the Copilot documentation. Only secrets with names prefixed with COPILOT_MCP_ will be available to your MCP configuration.

In your GitHub repository, navigate to Settings > Code & automation > Copilot > Coding agent and add the following configuration in the MCP configuration section:

GitHub Copilot coding agent with SonarQube Cloud:

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN=$SONAR_TOKEN",
        "-e",
        "SONARQUBE_ORG=$SONAR_ORG",
        "mcp/sonarqube"
      ],
      "env": {
        "SONAR_TOKEN": "COPILOT_MCP_<YourSonarQubeToken>",
        "SONAR_ORG": "COPILOT_MCP_<YourOrganizationName>"
      },
      "tools": ["*"]
    }
  }
}

GitHub Copilot coding agent with SonarQube Server:

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN=$SONAR_TOKEN",
        "-e",
        "SONARQUBE_URL=$SONAR_URL",
        "mcp/sonarqube"
      ],
      "env": {
        "SONAR_TOKEN": "COPILOT_MCP_<YourSonarQubeUserToken>",
        "SONAR_URL": "COPILOT_MCP_<YourSonarQubeURL>"
      },
      "tools": ["*"]
    }
  }
}

Setup in Kiro

Create or edit an existing .kiro/settings/mcp.json file in your workspace directory, then add the following configuration:

Kiro with SonarQube Cloud:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-e", 
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_ORG",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeToken>",
        "SONARQUBE_ORG": "<YourOrganizationName>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Kiro with SonarQube Server:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name",
        "sonarqube-mcp-server",
        "--rm",
        "-e", 
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeUserToken>",
        "SONARQUBE_URL": "<YourSonarQubeURL>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Setup in Windsurf

Automatic MCP configuration

Select the icon, Configure MCP Server from the CONNECTED MODE view window to use your connected mode credentials to start using the SonarQube MCP Server. The same workflow is available in the AI AGENTS CONFIGURATION view.

Check out our YouTube demo to watch the Windsurf & SonarQube MCP Server integration in action.

With an HTTP transport server

Please see the Transport mode article for details and code samples.

Manual configuration

SonarQube MCP Server is available as a Windsurf plugin. Follow these instructions:

Select Plugins at the top right of the Cascade view.
Search for sonarqube on the Plugin store.
Select Install.
Add the required SonarQube user token. Then add the organization key if you want to connect with SonarQube Cloud, or the SonarQube URL if you want to connect to SonarQube Server or SonarQube Community Build.

Using the SonarQube MCP Server tools

Once you’ve set up the Sonar MCP Server in Windsurf, you can use the tools it provides in the agent mode. See the Tools page for a full list of available tools.

See also the Windsurf docs for information on adding explicit context.

Setup in Zed

Zed is a next generation editor that sometimes requires a special configuration. Should you need it, we have a separate repository for Zed: https://github.com/SonarSource/sonarqube-mcp-server-zed. Otherwise, the installation instructions are relatively straight forward.

Install the extension

Navigate to the Extensions view in Zed and search for SonarQube MCP Server. When installing the extension, you will be prompted to enter the necessary environment variables:

Zed with SonarQube Cloud:

{
  "sonarqube_token": "<YourSonarQubeToken>",
  "sonarqube_org": "<YourOrganizationName>",
  "docker_path": "<YourDockerPath>"
}

Zed with SonarQube Server:

{
  "sonarqube_token": "<YourSonarQubeUserToken>",
  "sonarqube_url": "<YourSonarQubeURL>",
  "docker_path": "<YourDockerPath>"
}

The docker_path is the path to a docker executable. Examples:

Linux/macOS: /usr/bin/docker or /usr/local/bin/docker
Windows: C:\Program Files\Docker\Docker\resources\bin\docker.exe

To build the build the extension, run cargo build.

The SonarQube MCP Server tools

Once you’ve set up the Sonar MCP Server with your IDE, you can start using the SonarQube MCP Server Tools that are available.

PreviousSonarQube MCP Server NextBuild and configure

Last updated 9 hours ago

Was this helpful?