SonarQube MCP Server

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

Security best practices

> 🔒 Important: Your SonarQube token is a sensitive credential. Follow these security practices:

When using CLI commands:

• Avoid hardcoding tokens in command-line arguments – they get saved in shell history
• Use environment variables – set tokens in environment variables before running commands

When using configuration files:

• Never commit tokens to version control
• Use environment variable substitution in config files when possible

🚀 Generate your configuration

The fastest way to get started is the **SonarQube MCP Server Configuration Generator** – an interactive tool that produces a ready-to-use configuration for your preferred AI agent client.

Manual setup

If you prefer to configure things yourself, the simplest method is to use our container image at sonarsource/sonarqube-mcp. Use `sonarsource/sonarqube-mcp` for automatic updates (with `--pull=always`), or pin to a version tag (e.g., `sonarsource/sonarqube-mcp:1.19.0.2785`) for reproducible deployments. 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.

Antigravity

SonarQube MCP Server is available in the Antigravity MCP Store. Follow these instructions:

1. Open the Agent Side Panel

2. Click the three dots (...) at the top right and select MCP Servers

3. Search for `SonarQube` and select Install

4. Provide the required SonarQube User token. You can also provide your organization key for SonarQube Cloud or the SonarQube URL if connecting to SonarQube Server.

For SonarQube Cloud US, set the URL to `https://sonarqube.us`.

Alternatively, you can manually configure the server via `mcp_config.json`:

• To connect with SonarQube Cloud:

In the Agent Side Panel, click the three dots (...) -> MCP Store -> Manage MCP Servers -> View raw config, and add the following:

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

For SonarQube Cloud US, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section and `"-e", "SONARQUBE_URL"` to the `args` array.

• To connect with SonarQube Server:

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

Claude Code

• To connect with SonarQube Cloud:

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  --env SONARQUBE_ORG=$SONAR_ORG \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

For SonarQube Cloud US, add `--env SONARQUBE_URL=https://sonarqube.us` to the command.

• To connect with SonarQube Server:

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  --env SONARQUBE_URL=$SONAR_URL \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL sonarsource/sonarqube-mcp

Codex CLI

Manually edit the configuration file at `~/.codex/config.toml` and add the following configuration:

• To connect with SonarQube Cloud:

[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"]
env = { "SONARQUBE_TOKEN" = "", "SONARQUBE_ORG" = "" }

For SonarQube Cloud US, add `"SONARQUBE_URL" = "https://sonarqube.us"` to the `env` section and `"-e", "SONARQUBE_URL"` to the `args` array.

• To connect with SonarQube Server:

[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"]
env = { "SONARQUBE_TOKEN" = "", "SONARQUBE_URL" = "" }

Cursor

• To connect with SonarQube Cloud:

For SonarQube Cloud US, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section in your MCP configuration after installation.

• To connect with SonarQube Server:

Gemini CLI

> Note: The Gemini CLI extension has moved to the sonarqube-agent-plugins repository. Please install it from there going forward.

You can install our MCP server extension by using the following command:

gemini extensions install https://github.com/SonarSource/sonarqube-agent-plugins

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

Environment Variables Required:

• For SonarQube Cloud:
  • `SONARQUBE_TOKEN` - Your SonarQube Cloud token
  • `SONARQUBE_ORG` - Your organization key
  • `SONARQUBE_URL` - (Optional) Set to `https://sonarqube.us` for SonarQube Cloud US

• For SonarQube Server:
  • `SONARQUBE_TOKEN` - Your SonarQube Server USER token
  • `SONARQUBE_URL` - Your SonarQube Server URL

Once installed, the extension will be installed under `/.gemini/extensions/sonarqube/gemini-extension.json`.

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.

• To connect with SonarQube Cloud:

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=,SONARQUBE_ORG=
Tools: *

For SonarQube Cloud US, add `-e, SONARQUBE_URL` to Arguments and `SONARQUBE_URL=https://sonarqube.us` to Environment Variables.

• To connect with SonarQube Server:

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_URL, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=,SONARQUBE_URL=
Tools: *

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

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:

• To connect with SonarQube Cloud:

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

For SonarQube Cloud US, add `"-e", "SONARQUBE_URL"` to the `args` array and `"SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL"` to the `env` section, then set the secret `COPILOT_MCP_SONARQUBE_URL=https://sonarqube.us`.

• To connect with SonarQube Server:

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

Kiro

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

• To connect with 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": "",
        "SONARQUBE_ORG": ""
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

For SonarQube Cloud US, add `"-e", "SONARQUBE_URL"` to the `args` array and `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section.

• To connect with SonarQube Server:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "-i",
        "--rm",
        "-e", 
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "",
        "SONARQUBE_URL": ""
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

VS Code

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

For SonarQube Cloud US, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section in your MCP configuration after installation.

Windsurf

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

1. Open Windsurf Settings > Cascade > MCP Servers and select Open MCP Marketplace

2. Search for `sonarqube` on the Cascade MCP Marketplace

3. Choose the SonarQube MCP Server and select Install

4. 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 Community Build.

For SonarQube Cloud US, set the URL to `https://sonarqube.us`.

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:

• When using SonarQube Cloud:

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

For SonarQube Cloud US, add `"sonarqube_url": "https://sonarqube.us"` to the configuration.

• When using SonarQube Server:

{
  "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`

> 💡 Tip: We recommend pulling the latest image regularly or before reporting issues to ensure you have the most up-to-date features and fixes.

Manual installation

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

• To connect with SonarQube Cloud:

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

• To connect with SonarQube Server:

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "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.

Configuration

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",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_ORG",
      "-e",
      "SONARQUBE_IDE_PORT",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "",
      "SONARQUBE_ORG": "",
      "SONARQUBE_IDE_PORT": ""
    }
  }
}

> 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.

Configuration

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

Base

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

Workspace Mount (Reducing Context Bloat)

By default, analysis tool `analyze_code_snippet` requires the agent to pass the full file content as a `fileContent` argument. For large files or when analyzing many files in a session, this significantly increases context window usage and cost.

Solution: mount your project directory into the container at `/app/mcp-workspace`. When this mount is detected, the server reads files directly from disk using the project-relative `filePath` argument — file content never passes through the agent context.

{
  "args": [
    "run", "-i", "--rm", "--init", "--pull=always",
    "-e", "SONARQUBE_TOKEN",
    "-e", "SONARQUBE_ORG",
    "-v", "/path/to/your/project:/app/mcp-workspace",
    "sonarsource/sonarqube-mcp"
  ]
}

When the mount is active:

• `run_advanced_code_analysis` becomes available if your organization is entitled to it
• `analyze_code_snippet`: `filePath` is required and `fileContent` is not used — the server resolves the file the same way

Selective Tool Enablement

By default, only important toolsets are enabled to reduce context overhead. You can enable additional toolsets as needed.

Available Toolsets

Examples

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

docker run --init --pull=always -i --rm \
  -e SONARQUBE_TOKEN="" \
  -e SONARQUBE_ORG="" \
  -e SONARQUBE_TOOLSETS="analysis,issues,quality-gates" \
  sonarsource/sonarqube-mcp

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 --init --pull=always -i --rm \
  -e SONARQUBE_TOKEN="" \
  -e SONARQUBE_ORG="" \
  -e SONARQUBE_READ_ONLY="true" \
  sonarsource/sonarqube-mcp

SonarQube Cloud

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

Examples:

• SonarQube Cloud: Only `SONARQUBE_TOKEN` and `SONARQUBE_ORG` are needed
• SonarQube Cloud US: Set `SONARQUBE_TOKEN`, `SONARQUBE_ORG`, and `SONARQUBE_URL=https://sonarqube.us`

SonarQube Server

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

> 💡 Configuration Tip (stdio mode): The presence of `SONARQUBE_ORG` determines whether you're connecting to SonarQube Cloud or Server. If `SONARQUBE_ORG` is set, SonarQube Cloud is used; otherwise, SonarQube Server is used.

Transport Modes

The MCP specification defines two transport mechanisms: Stdio and Streamable HTTP. The SonarQube MCP Server supports both:

> Note: Streamable HTTP is the current MCP network transport. The older SSE-only HTTP transport from earlier MCP versions is deprecated and not supported.

1. Stdio (Default - Recommended for Local Development)

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

Example - Docker with 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": "",
        "SONARQUBE_ORG": ""
      }
    }
  }
}

2. HTTP (Streamable HTTP)

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

> ⚠️ Not Recommended: Use Stdio for local development or HTTPS (Streamable HTTP) for multi-user production deployments.

Note: In Streamable HTTP mode (HTTP or HTTPS), the server is stateless — each client request must include an `Authorization: Bearer ` header carrying the user's own SonarQube token. For SonarQube Cloud, the organization is resolved as follows:

• If `SONARQUBE_ORG` is set at server startup, all requests are routed to that organization. Clients must not send a `SONARQUBE_ORG` header — doing so will result in an error.
• If `SONARQUBE_ORG` is not set at server startup, each client must supply a `SONARQUBE_ORG` header on every request.

Clients can also narrow the visible tools per-request by supplying `SONARQUBE_TOOLSETS` and/or `SONARQUBE_READ_ONLY` headers; these apply additional filtering on top of the server-level configuration — they can only reduce the scope, never expand it.

No session state is maintained between requests.

> Deprecated: The `SONARQUBE_TOKEN` request header is still accepted for backward compatibility but will be removed in a future version. Migrate to `Authorization: Bearer `.

3. HTTPS (Streamable HTTP over TLS) (Recommended for Multi-User Production Deployments)

Secure Streamable HTTP transport with TLS encryption. Requires SSL certificates.

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

SSL Certificate Configuration (Optional):

Example - Docker with SonarQube Cloud:

> Note: When running in a container, set `SONARQUBE_HTTP_HOST=0.0.0.0` so the container listens on all interfaces and the runtime's port mapping works, and set `SONARQUBE_MCP_IN_CONTAINER=true` to tell the server it is inside a container. The official Docker image sets the latter automatically; set it yourself when using other OCI runtimes (Podman, Kubernetes, Nomad, etc.). The host-side port flag controls who can reach the server from outside the container. `SONARQUBE_HTTP_HOST=0.0.0.0` only controls where the server listens inside the container — browser CORS still allows localhost origins by default.

For a server running locally on your machine (accessible only from localhost):

docker run --init --pull=always -p 127.0.0.1:8443:8443 \
  -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  -e SONARQUBE_TRANSPORT=https \
  -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  -e SONARQUBE_HTTP_PORT=8443 \
  -e SONARQUBE_TOKEN="" \
  -e SONARQUBE_ORG="" \
  sonarsource/sonarqube-mcp

For a server accessible from the network (remote deployments):

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

Client Configuration (SonarQube Cloud):

{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization": "Bearer ",
        "SONARQUBE_ORG": "",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

Client Configuration (SonarQube Server):

{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization": "Bearer ",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

> Note: `SONARQUBE_TOOLSETS` and `SONARQUBE_READ_ONLY` are optional per-request headers that narrow the server-level tool set for that specific request. They can only reduce scope — they cannot enable toolsets or lift restrictions beyond what the server was launched with.

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

Service Endpoints

When running in Streamable HTTP mode (`http` or `https`), the server exposes a few unauthenticated service endpoints in addition to the MCP endpoint at `/mcp`. These are intended for service-to-service use (monitoring, orchestration, client compatibility checks) and do not require an `Authorization` header.

These endpoints are not available when running with the Stdio transport.

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.

Configuration

Using Volume Mount

Mount a directory containing your certificates when running the container:

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

Supported Certificate Formats

The container supports the following certificate formats:

• `.crt` files (PEM or DER encoded)
• `.pem` files (PEM encoded)

MCP Configuration with Certificates

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

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

> Note: Running the server from a JAR instead of the container? The volume mount above installs certificates into the container's OS trust store, which the server also reads. If you cannot use the OS trust store — notably on Windows, where it is not consulted — point the JVM at a Java truststore holding the CA certificate: `-Djavax.net.ssl.trustStore=/path/to/truststore.p12 -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=`. It is added on top of the default trusted certificates.

Proxy

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

Configuration

HTTP/HTTPS Proxy

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

Common Proxy Properties:

HTTP/HTTPS Proxy Authentication:

SOCKS5 Proxy

SOCKS5 proxies are supported.

Client Certificate (Mutual TLS)

If your SonarQube Server requires clients to present a certificate during the TLS handshake (mutual TLS), you can provide a PKCS12 keystore by mounting it into the container and passing its location via `JAVA_OPTS`.

Configuration

Using a PKCS12 keystore

Mount your `.p12` or `.pfx` file into the container and set the `JAVA_OPTS` environment variable with the keystore properties:

docker run --init --pull=always -i --rm \
  -v /path/to/client.p12:/etc/ssl/mcp/client.p12:ro \
  -e JAVA_OPTS="-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=" \
  -e SONARQUBE_TOKEN="" \
  -e SONARQUBE_URL="" \
  sonarsource/sonarqube-mcp

> Note: The certificate file must be readable by the container process. Check and fix permissions if needed:

> ```bash

> ls -la /path/to/client.p12 # look for -rw-r--r-- (644) or wider

> chmod 644 /path/to/client.p12 # grant read access to the container user

> ```

Omit `-Djavax.net.ssl.keyStorePassword` if the keystore has no passphrase. Note that the passphrase used here would be visible through `docker inspect` or process list.

MCP Configuration with a Client Certificate

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run", "--init", "--pull=always", "-i", "--rm",
      "-v", "/path/to/client.p12:/etc/ssl/mcp/client.p12:ro",
      "-e", "JAVA_OPTS",
      "-e", "SONARQUBE_TOKEN",
      "-e", "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "JAVA_OPTS": "-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=",
      "SONARQUBE_TOKEN": "",
      "SONARQUBE_URL": ""
    }
  }
}

Using a PKCS12 keystore with a standalone JAR

When running the server from a JAR, pass the keystore properties as JVM arguments before `-jar`:

java \
  -Djavax.net.ssl.keyStore=/path/to/client.p12 \
  -Djavax.net.ssl.keyStoreType=PKCS12 \
  -Djavax.net.ssl.keyStorePassword= \
  -jar

Omit `-Djavax.net.ssl.keyStorePassword` if the keystore has no passphrase.

MCP Configuration with a Client Certificate (JAR)

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-Djavax.net.ssl.keyStore=/path/to/client.p12",
      "-Djavax.net.ssl.keyStoreType=PKCS12",
      "-Djavax.net.ssl.keyStorePassword=",
      "-jar",
      ""
    ],
    "env": {
      "SONARQUBE_TOKEN": "",
      "SONARQUBE_URL": ""
    }
  }
}

> Note: PEM certificate and key files (separate `.crt`/`.key` files) must be converted to PKCS12 format first. Use `openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12` to convert them.

Tools

Analysis

• analyze_code_snippet - Analyze file content with SonarQube analyzers to identify code quality and security issues. Always analyzes the complete file content for accuracy. Optionally filter results to a specific code snippet.

> Deprecated: `analyze_code_snippet` will be removed in a future release. Connect SonarQube for IDE to use `analyze_file_list`, or enable Vortex analysis for your organization to use `run_advanced_code_analysis` (see below).

Usage:

Parameters:

Supported Languages: Java, Kotlin, Python, Ruby, Go, JavaScript (`js`, `jsx`), TypeScript (`ts`, `tsx`), JSP, PHP, XML, HTML, CSS, CloudFormation, Kubernetes, Terraform, Azure Resource Manager, Ansible, Docker, Secrets detection

When integration with SonarQube for IDE is enabled: _(these two tools are tagged under both the `analysis` and `ide` toolsets)_

• analyze_file_list - Analyze files in the current working directory using SonarQube for IDE. This tool connects to a running SonarQube for IDE instance to perform code quality analysis on a list of files.

• toggle_automatic_analysis - Enable or disable SonarQube for IDE automatic analysis. When enabled, SonarQube for IDE will automatically analyze files as they are modified in the working directory. When disabled, automatic analysis is turned off.

On SonarQube Server, stdio lists Vortex context tools and `run_advanced_code_analysis` when both the CAG and A3S hubs are entitled.

When Vortex analysis is enabled:

> Requires having the workspace mounted at `/app/mcp-workspace`

• run_advanced_code_analysis - Run Vortex analysis on a single file. Organization is inferred from MCP configuration (SonarQube Server uses the nil UUID placeholder).

Coverage

• search_files_by_coverage - Search for files in a project sorted by coverage (ascending - worst coverage first). This tool helps identify files that need test coverage improvements.
  • `projectKey` - The project key to search in - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  • `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  • `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  • `maxCoverage` - Maximum coverage threshold (0-100). Only return files with coverage

Architecture Tools

• search_by_signature_patterns - Find code elements (classes, methods, interfaces, ...) by their declaration signatures using regex patterns.

• search_by_body_patterns - Find code elements by their implementation body using regex patterns. Useful for locating where APIs or patterns are actually used.

• get_upstream_call_flow - Trace what functions call a given function. Useful for finding all callers and entry points, and understanding what breaks if a signature changes.

• get_downstream_call_flow - Trace what functions a given function calls. Useful for impact analysis and understanding execution flow.

• get_source_code - Get complete source code (signature and body) for a code element by its fully qualified name.

• get_type_hierarchy - Get the full inheritance hierarchy for a class-like structure (class, interface, enum, record, exception, struct). Essential for understanding inheritance trees and refactoring.

• get_references - Get direct inbound and outbound code references for a class or module. Returns only direct (non-transitive) references.

• get_current_architecture - Get a hierarchical architecture graph filtered by path prefix and depth. Useful for exploring module structure and high-level dependencies.

• get_intended_architecture - Get user-defined architectural constraints specifying which modules are allowed to depend on others.

Guidelines Tools

• get_guidelines - Get coding guidelines based on SonarQube project issues, catalog categories, or a combination of both.

Third-party Dependency Tools

• check_dependency - Check a third-party dependency for security vulnerabilities, supply-chain malware, and license compliance before adding or updating it.

Context Augmentation Environment Variables

• To be provided when not using git, or when the git branch name doesn't match the branch name in SonarQube.

Project-Specific Configuration (Recommended)

First, export the `SONARQUBE_TOKEN` environment variable with a valid Personal Access Token (PAT) for your project.

# macOS/Linux (Bash/Zsh)
export SONARQUBE_TOKEN="{}"

Then, mount the project workspace to give the Context Augmentation server direct access to your source files:

{
  "mcpServers": {
    "sonarqube-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-e", "SONARQUBE_TOOLSETS",
        "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_ORG": "",
        "SONARQUBE_PROJECT_KEY": "",
        "SONARQUBE_TOOLSETS": "cag"
      }
    }
  }
}

Important: In a project-scoped config, do not put `SONARQUBE_TOKEN` in the env block. Export it as an environment variable (`export SONARQUBE_TOKEN=...`). Docker will forward it into the container via `-e SONARQUBE_TOKEN`.

Agentic Readiness

Note: Agentic Readiness tools are only available on SonarQube Cloud and require the feature to be enabled for your organization.

• start_agentic_readiness_assessment - Start an agentic readiness assessment for a project. Returns immediately with status `PENDING` and an `assessmentId`. Use `get_agentic_readiness_assessment` to poll for results.
  • `projectKey` - The project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  • `branch` - Branch to assess. Omit to use the project's default branch - _String_

• get_agentic_readiness_assessment - Retrieve the result of an assessment. Re-call with the same `assessmentId` until status is `COMPLETED`, `FAILED`, or `INTERRUPTED`. When completed, returns the overall level and a per-pillar breakdown with recommended actions and evidence.
  • `assessmentId` - The assessment ID returned by `start_agentic_readiness_assessment` - _Required String_

• list_agentic_readiness_assessments - List all assessments for a project, newest first. Use `get_agentic_readiness_assessment` for full pillar-level results.
  • `projectKey` - The project key to list assessments for - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  • `branch` - Filter assessments by branch name. Omit to list assessments for all branches - _String_
  • `pageIndex` - 1-based page index (default: 1) - _Number_
  • `pageSize` - Number of items per page, max 100 (default: 50) - _Number_

Example Prompts

Once you've set up the SonarQube MCP Server, here are some example prompts for common real-world scenarios:

Fixing a Failing Quality Gate

My quality gate is failing for my project. Can you help me understand why and fix the most critical issues?

The quality gate on my feature branch is red. What do I need to fix to get it passing before I can merge to main?

Pre-Release and Pre-Merge Checks

I'm about to merge my pull request  for the  project. Can you check if there are any quality issues I should address first?

We're deploying to production tomorrow. Can you check the quality gate status and alert me to any critical issues in this branch?

Improving Code Quality

I want to reduce technical debt in my project. What are the top issues I should prioritize?

Our code coverage dropped below 70%. Can you identify which files have the lowest coverage and help me improve it?

Understanding and Fixing Issues

I have 15 new code smells in my latest commit. Can you explain what they are and help me fix them?

SonarQube flagged a critical security vulnerability in . What's the issue and how do I fix it?

Security and Dependency Management

We need to pass a security audit. Can you check all our projects for security vulnerabilities and create a prioritized list of what needs to be fixed?

Are there any known vulnerabilities in our dependencies? Check this project for dependency risks.

Code Review Assistance

I just wrote this authentication function. Can you analyze it for security issues and code quality problems before I commit?

Review the changes in  for any potential bugs or security issues.

Project Health Monitoring

Give me a health report for my project: quality gate status, number of bugs, Security Hotspots, and code coverage.

Compare code quality between our main branch and the develop branch. Are we introducing new issues?

Team Collaboration

What are the most common rule violations across all our projects? We might need to update our coding standards.

Show me all the issues that were marked as false positives in the last month. Are we seeing patterns that suggest our rules need adjustment?

Build

Prefer the sonarsource/sonarqube-mcp container image.

To run the server as a standalone JAR without Docker, download a pre-built release from the SonarSource binaries repository. Every released version is published there as `sonarqube-mcp-server-.jar` (for example, `sonarqube-mcp-server-1.19.0.2785.jar`).

Run from JAR

Download the JAR for the version you want from the binaries repository, then configure your MCP client to run it with Java 21 or later:

• To connect with SonarQube Cloud:

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

• To connect with SonarQube Server:

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

Build from source

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/`.

After adding or updating dependencies, regenerate the lock files:

./gradlew :dependencies --write-locks
./gradlew :its:dependencies --write-locks

Use the Run from JAR configuration above, pointing `` to the JAR in `build/libs/`.

Troubleshooting

Application logs are written to the `STORAGE_PATH/logs/mcp.log` file by default. To disable file logging entirely, set `SONARQUBE_LOG_TO_FILE_DISABLED=true`.

Common Issues

"Feature is not working" or "Missing tools/functionality"

You may be running an outdated Docker image. Docker caches images locally, so you won't automatically receive updates.

Solution: Update to the latest version:

docker pull sonarsource/sonarqube-mcp

After pulling the latest image, restart your MCP client to use the updated version.

Optionally, add the `--pull=always` flag to your docker run command to always check for and pull the latest version:

docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

"I want to pin to a specific version"

Browse available tags at sonarsource/sonarqube-mcp and reference the version you want:

docker pull sonarsource/sonarqube-mcp:1.19.0.2785

docker run --init -i --rm \
  -e SONARQUBE_TOKEN -e SONARQUBE_ORG \
  sonarsource/sonarqube-mcp:1.19.0.2785

In your MCP client config, use `sonarsource/sonarqube-mcp:` instead of `sonarsource/sonarqube-mcp` and remove `--pull=always` so Docker does not silently upgrade the image.

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.