GitHub - SonarSource/sonarqube-mcp-server: SonarQube MCP Server (original) (raw)

SonarQube MCP Server

Build Quality Gate Status

The SonarQube MCP Server is a Model Context Protocol (MCP) server that enables seamless integration with SonarQube Server or Cloud for code quality and security. It also supports the analysis of code snippet directly within the agent context.

Quick setup

The simplest method is to rely on our container image hosted at mcp/sonarqube. Read below if you want to build it locally.

Note: While the examples below use docker, any OCI-compatible container runtime works (e.g., Podman, nerdctl). Simply replace docker with your preferred tool.

Details Claude Code

claude mcp add sonarqube --env SONARQUBE_TOKEN=<token> --env SONARQUBE_ORG=<org> -- docker run -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG mcp/sonarqube

claude mcp add sonarqube --env SONARQUBE_TOKEN=<token> --env SONARQUBE_URL=<url> -- docker run -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL mcp/sonarqube

Details Codex CLI

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

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

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

Details Cursor

Install for SonarQube Cloud

Install for SonarQube Server

Details Gemini CLI

You can install our 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="<token>"
SONARQUBE_ORG="<org>" // For SonarQube Cloud, empty otherwise
SONARQUBE_URL="<url>" // For SonarQube Server, empty otherwise

Once installed, the extension will be installed under <home>/.gemini/extensions/sonarqube-mcp-server/gemini-extension.json.

Details GitHub Copilot CLI

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

/mcp add

You will have to provide different information about the MCP server, you can use tab to navigate between fields.

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

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

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

Details GitHub Copilot coding agent

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

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 under Settings -> Copilot -> Coding agent, and add the following configuration in the MCP configuration section:

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN=$SONAR_TOKEN",
        "-e",
        "SONARQUBE_ORG=$SONAR_ORG",
        "mcp/sonarqube"
      ],
      "env": {
        "SONAR_TOKEN": "COPILOT_MCP_SONARQUBE_TOKEN",
        "SONAR_ORG": "COPILOT_MCP_SONARQUBE_ORG"
      },
      "tools": ["*"]
    }
  }
}

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN=$SONAR_TOKEN",
        "-e",
        "SONARQUBE_URL=$SONAR_URL",
        "mcp/sonarqube"
      ],
      "env": {
        "SONAR_TOKEN": "COPILOT_MCP_SONARQUBE_USER_TOKEN",
        "SONAR_URL": "COPILOT_MCP_SONARQUBE_URL"
      },
      "tools": ["*"]
    }
  }
}

Details Kiro

Create a .kiro/settings/mcp.json file in your workspace directory (or edit if it already exists), add the following configuration:

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

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

Details VS Code

You can use the following buttons to simplify the installation process within VS Code.

Install for SonarQube Cloud

Install for SonarQube Server

Details Windsurf

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

  1. Click on the Plugins button at the top right of the Cascade view
  2. Search for sonarqube on the Plugin store
  3. Click Install
  4. Add the required SonarQube 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 Community Build. Details Zed

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

{
  "sonarqube_token": "YOUR_SONARQUBE_TOKEN",
  "sonarqube_org": "SONARQUBE_ORGANIZATION_KEY",
  "docker_path": "DOCKER_PATH"
}

{
  "sonarqube_token": "YOUR_SONARQUBE_USER_TOKEN",
  "sonarqube_url": "YOUR_SONARQUBE_SERVER_URL",
  "docker_path": "DOCKER_PATH"
}

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

Manual installation

You can manually install the SonarQube MCP server by copying the following snippet in the MCP servers configuration file:

{ "sonarqube": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "mcp/sonarqube" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_ORG": "" } } }

{ "sonarqube": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "mcp/sonarqube" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } }

Integration with SonarQube for IDE

The SonarQube MCP Server can integrate with SonarQube for IDE to further enhance your development workflow, providing better code analysis and insights directly within your IDE.

When using SonarQube for IDE, the SONARQUBE_IDE_PORT environment variable should be set with the correct port number. SonarQube for VS Code includes a Quick Install button, which automatically sets the correct port configuration.

For example, with SonarQube Cloud:

{ "sonarqube": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "-e", "SONARQUBE_IDE_PORT", "mcp/sonarqube" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_ORG": "", "SONARQUBE_IDE_PORT": "<64120-64130>" } } }

When running the MCP server in a container on Linux, the container cannot access the SonarQube for IDE embedded server running on localhost. To allow the container to connect to the SonarQube for IDE server, add the --network=host option to your container run command.

Build

SonarQube MCP Server requires a Java Development Kit (JDK) version 21 or later to build.

Run the following Gradle command to clean the project and build the application:

./gradlew clean build -x test

The JAR file will be created in build/libs/.

You will then need to manually copy and paste the MCP configuration, as follows:

{ "sonarqube": { "command": "java", "args": [ "-jar", "" ], "env": { "STORAGE_PATH": "", "SONARQUBE_TOKEN": "", "SONARQUBE_ORG": "" } } }

{ "sonarqube": { "command": "java", "args": [ "-jar", "" ], "env": { "STORAGE_PATH": "", "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } }

Configuration

Depending on your environment, you should provide specific environment variables.

Base

You should add the following variable when running the MCP Server:

Environment variable Description
STORAGE_PATH Mandatory absolute path to a writable directory where SonarQube MCP Server will store its files (e.g., for creation, updates, and persistence), it is automatically provided when using the container image
SONARQUBE_IDE_PORT Optional port number between 64120 and 64130 used to connect SonarQube MCP Server with SonarQube for IDE.

Selective Tool Enablement

By default, all tools are enabled. You can selectively enable specific toolsets to reduce context overhead and focus on specific functionality.

Environment variable Description
SONARQUBE_TOOLSETS Comma-separated list of toolsets to enable. When set, only these toolsets will be available. If not set, all tools are enabled. Note: The projects toolset is always enabled as it's required to find project keys for other operations.
SONARQUBE_READ_ONLY When set to true, enables read-only mode which disables all write operations (changing issue status for example). This filter is cumulative with SONARQUBE_TOOLSETS if both are set. Default: false.

Details Available Toolsets

Toolset Key Description
Analysis analysis Code analysis tools (analyze code snippets and files)
Issues issues Search and manage SonarQube issues
Projects projects Browse and search SonarQube projects
Quality Gates quality-gates Access quality gates and their status
Rules rules Browse and search SonarQube rules
Sources sources Access source code and SCM information
Measures measures Retrieve metrics and measures (includes both measures and metrics tools)
Languages languages List supported programming languages
Portfolios portfolios Manage portfolios and enterprises (Cloud and Server)
System system System administration tools (Server only)
Webhooks webhooks Manage webhooks
Dependency Risks dependency-risks Analyze dependency risks and security issues (SCA)

Examples

Enable analysis, issues, and quality gates toolsets (using Docker with SonarQube Cloud):

docker run -i --rm
-e SONARQUBE_TOKEN=""
-e SONARQUBE_ORG=""
-e SONARQUBE_TOOLSETS="analysis,issues,quality-gates"
mcp/sonarqube

Note: The projects toolset is always enabled automatically, so you don't need to include it in SONARQUBE_TOOLSETS.

Enable read-only mode (using Docker with SonarQube Cloud):

docker run -i --rm
-e SONARQUBE_TOKEN=""
-e SONARQUBE_ORG=""
-e SONARQUBE_READ_ONLY="true"
mcp/sonarqube

SonarQube Cloud

To enable full functionality, the following environment variables must be set before starting the server:

Environment variable Description
SONARQUBE_TOKEN Your SonarQube Cloud token
SONARQUBE_ORG Your SonarQube Cloud organization key

Connecting your SonarQube MCP Server with your SonarQube Cloud US instance requires the use of the environment variable SONARQUBE_CLOUD_URL.

SonarQube Server

Environment variable Description
SONARQUBE_TOKEN Your SonarQube Server USER token
SONARQUBE_URL Your SonarQube Server URL

⚠️ Connection to SonarQube Server requires a token of type USER and will not function properly if project tokens or global tokens are used.

Transport Modes

The SonarQube MCP Server supports three transport modes:

1. Stdio (Default - Recommended for Local Development)

The recommended mode for local development and single-user setups, used by all MCP clients.

Example - Docker with SonarQube Cloud:

{ "mcpServers": { "sonarqube": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "mcp/sonarqube"], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_ORG": "" } } } }

2. HTTP

Unencrypted HTTP transport. Use HTTPS instead for multi-user deployments.

⚠️ Not Recommended: Use Stdio for local development or HTTPS for multi-user production deployments.

Environment variable Description Default
SONARQUBE_TRANSPORT Set to http to enable HTTP transport Not set (stdio)
SONARQUBE_HTTP_PORT Port number (1024-65535) 8080
SONARQUBE_HTTP_HOST Host to bind (defaults to localhost for security) 127.0.0.1

Note: In HTTP(S) mode, each client sends their own token via the SONARQUBE_TOKEN header. The server's SONARQUBE_TOKEN is only used for initialization.

Secure multi-user transport with TLS encryption. Requires SSL certificates.

✅ Recommended for Production: Use HTTPS when deploying the MCP server for multiple users. The server binds to 127.0.0.1 (localhost) by default for security.

Environment variable Description Default
SONARQUBE_TRANSPORT Set to https to enable HTTPS transport Not set (stdio)
SONARQUBE_HTTP_PORT Port number (typically 8443 for HTTPS) 8080
SONARQUBE_HTTP_HOST Host to bind (defaults to localhost for security) 127.0.0.1

SSL Certificate Configuration (Optional):

Environment variable Description Default
SONARQUBE_HTTPS_KEYSTORE_PATH Path to keystore file (.p12 or .jks) /etc/ssl/mcp/keystore.p12
SONARQUBE_HTTPS_KEYSTORE_PASSWORD Keystore password sonarlint
SONARQUBE_HTTPS_KEYSTORE_TYPE Keystore type (PKCS12 or JKS) PKCS12

Example - Docker with SonarQube Cloud:

docker run -p 8443:8443
-v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro
-e SONARQUBE_TRANSPORT=https
-e SONARQUBE_HTTP_PORT=8443
-e SONARQUBE_TOKEN=""
-e SONARQUBE_ORG=""
mcp/sonarqube

Client Configuration:

{ "mcpServers": { "sonarqube-https": { "url": "https://your-server:8443/mcp", "headers": { "SONARQUBE_TOKEN": "" } } } }

Note: For local development, use Stdio transport instead (the default). HTTPS is intended for multi-user production deployments with proper SSL certificates.

Custom Certificates

If your SonarQube Server uses a self-signed certificate or a certificate from a private Certificate Authority (CA), you can add custom certificates to the container that will automatically be installed.

Details Configuration

Using Volume Mount

Mount a directory containing your certificates when running the container:

docker run -i --rm
-v /path/to/your/certificates/:/usr/local/share/ca-certificates/:ro
-e SONARQUBE_TOKEN=""
-e SONARQUBE_URL=""
mcp/sonarqube

Supported Certificate Formats

The container supports the following certificate formats:

MCP Configuration with Certificates

When using custom certificates, you can modify your MCP configuration to mount the certificates:

{ "sonarqube": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/path/to/your/certificates/:/usr/local/share/ca-certificates/:ro", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "mcp/sonarqube" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } }

Proxy

The SonarQube MCP Server supports HTTP proxies through standard Java proxy system properties.

Details Configuration

Configuring Proxy Settings

You can configure proxy settings using Java system properties. These can be set as environment variables or passed as JVM arguments.

Common Proxy Properties:

Property Description Example
http.proxyHost HTTP proxy hostname proxy.example.com
http.proxyPort HTTP proxy port 8080
https.proxyHost HTTPS proxy hostname proxy.example.com
https.proxyPort HTTPS proxy port 8443
http.nonProxyHosts Hosts that bypass the proxy (pipe-separated) localhost|127.0.0.1

Proxy Authentication

If your proxy requires authentication, the SonarQube MCP Server uses Java's standard authentication mechanism. You can set up proxy credentials using Java system properties:

Property Description Example
http.proxyUser HTTP proxy username myuser
http.proxyPassword HTTP proxy password mypassword
https.proxyUser HTTPS proxy username myuser
https.proxyPassword HTTPS proxy password mypassword

Tools

Analysis

When integration with SonarQube for IDE is enabled:

Dependency Risks

Note: Dependency risks are only available when connecting to SonarQube Server 2025.4 Enterprise or higher with SonarQube Advanced Security enabled.

Enterprises

Note: Enterprises are only available when connecting to SonarQube Cloud.

Issues

Languages

Measures

Metrics

Portfolios

Projects

Quality Gates

Rules

Sources

System

Note: System tools are only available when connecting to SonarQube Server.

Webhooks

Troubleshooting

Applications logs will be written to the STORAGE_PATH/logs/mcp.log file.

Data and telemetry

This server collects anonymous usage data and sends it to SonarSource to help improve the product. No source code or IP address is collected, and SonarSource does not share the data with anyone else. Collection of telemetry can be disabled with the following system property or environment variable: TELEMETRY_DISABLED=true. Click here to see a sample of the data that are collected.

License

Copyright 2025 SonarSource.

Licensed under the SONAR Source-Available License v1.0. Using the SonarQube MCP Server in compliance with this documentation is a Non-Competitive Purpose and so is allowed under the SSAL.

Your use of SonarQube via MCP is governed by the SonarQube Cloud Terms of Service or SonarQube Server Terms and Conditions, including use of the Results Data solely for your internal software development purposes.