
Connects Claude to SonarQube Cloud or self-hosted Server instances for code quality and security analysis. You get access to project metrics, issue tracking, and quality gate status through the standard SonarQube REST APIs. The server can also analyze code snippets directly within the agent context, which is handy when you want real-time feedback on code you're drafting without pushing to a repository. Setup uses Docker by default and requires a SonarQube token for authentication. Reach for this when you want Claude to check quality gates, fetch technical debt metrics, or scan code against your organization's SonarQube rules during development conversations.
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.
🔒 Important: Your SonarQube token is a sensitive credential. Follow these security practices:
When using CLI commands:
When using configuration files:
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.
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 replacedockerwith your preferred tool.
SonarQube MCP Server is available in the Antigravity MCP Store. Follow these instructions:
SonarQube and select InstallFor SonarQube Cloud US, set the URL to https://sonarqube.us.
Alternatively, you can manually configure the server via mcp_config.json:
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": "<YOUR_TOKEN>",
"SONARQUBE_ORG": "<YOUR_ORG>"
}
}
}
}
For SonarQube Cloud US, manually add "SONARQUBE_URL": "https://sonarqube.us" to the env section and "-e", "SONARQUBE_URL" to the args array.
{
"mcpServers": {
"sonarqube": {
"command": "docker",
"args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"],
"env": {
"SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
"SONARQUBE_URL": "<YOUR_SERVER_URL>"
}
}
}
}
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.
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
Manually edit the configuration file at ~/.codex/config.toml and add the following configuration:
[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"]
env = { "SONARQUBE_TOKEN" = "<YOUR_USER_TOKEN>", "SONARQUBE_ORG" = "<YOUR_ORG>" }
For SonarQube Cloud US, add "SONARQUBE_URL" = "https://sonarqube.us" to the env section and "-e", "SONARQUBE_URL" to the args array.
[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"]
env = { "SONARQUBE_TOKEN" = "<YOUR_TOKEN>", "SONARQUBE_URL" = "<YOUR_SERVER_URL>" }
For SonarQube Cloud US, manually add "SONARQUBE_URL": "https://sonarqube.us" to the env section in your MCP configuration after installation.
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 tokenSONARQUBE_ORG - Your organization keySONARQUBE_URL - (Optional) Set to https://sonarqube.us for SonarQube Cloud USFor SonarQube Server:
SONARQUBE_TOKEN - Your SonarQube Server USER tokenSONARQUBE_URL - Your SonarQube Server URLOnce installed, the extension will be installed under <home>/.gemini/extensions/sonarqube/gemini-extension.json.
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, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=<YOUR_TOKEN>,SONARQUBE_ORG=<YOUR_ORG>
Tools: *
For SonarQube Cloud US, add -e, SONARQUBE_URL to Arguments and SONARQUBE_URL=https://sonarqube.us to Environment Variables.
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=<YOUR_USER_TOKEN>,SONARQUBE_URL=<YOUR_SERVER_URL>
Tools: *
The configuration file is located at ~/.copilot/mcp-config.json.
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",
"--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.
{
"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": ["*"]
}
}
}
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",
"--init",
"--pull=always",
"-i",
"--rm",
"-e",
"SONARQUBE_TOKEN",
"-e",
"SONARQUBE_ORG",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "<YOUR_TOKEN>",
"SONARQUBE_ORG": "<YOUR_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.
{
"mcpServers": {
"sonarqube": {
"command": "docker",
"args": [
"run",
"--init",
"--pull=always",
"-i",
"--rm",
"-e",
"SONARQUBE_TOKEN",
"-e",
"SONARQUBE_URL",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
"SONARQUBE_URL": "<YOUR_SERVER_URL>"
},
"disabled": false,
"autoApprove": []
}
}
}
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.
SonarQube MCP Server is available as a Windsurf plugin. Follow these instructions:
sonarqube on the Cascade MCP MarketplaceFor SonarQube Cloud US, set the URL to https://sonarqube.us.
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"
}
For SonarQube Cloud US, add "sonarqube_url": "https://sonarqube.us" to the configuration.
{
"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.
You can manually install the SonarQube MCP server by copying the following snippet in the MCP servers configuration file:
{
"sonarqube": {
"command": "docker",
"args": [
"run",
"--init",
"--pull=always",
"-i",
"--rm",
"-e",
"SONARQUBE_TOKEN",
"-e",
"SONARQUBE_ORG",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "<token>",
"SONARQUBE_ORG": "<org>"
}
}
}
{
"sonarqube": {
"command": "docker",
"args": [
"run",
"--init",
"--pull=always",
"-i",
"--rm",
"-e",
"SONARQUBE_TOKEN",
"-e",
"SONARQUBE_URL",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "<token>",
"SONARQUBE_URL": "<url>"
}
}
}
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",
"--init",
"--pull=always",
"-i",
"--rm",
"-e",
"SONARQUBE_TOKEN",
"-e",
"SONARQUBE_ORG",
"-e",
"SONARQUBE_IDE_PORT",
"sonarsource/sonarqube-mcp"
],
"env": {
"SONARQUBE_TOKEN": "<token>",
"SONARQUBE_ORG": "<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=hostoption to your container run command.
Depending on your environment, you should provide specific environment variables.
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_PROJECT_KEY | Optional default project key. When set, all tools that require a project key will use this value automatically — the projectKey parameter is removed from their schema entirely. Useful when working on a single project. |
SONARQUBE_IDE_PORT | Optional port number between 64120 and 64130 used to connect SonarQube MCP Server with SonarQube for IDE. |
SONARQUBE_DEBUG_ENABLED | When set to true, enables debug logging. Debug logs are written to both the log file and STDERR. Useful for troubleshooting connectivity or configuration issues. Default: false. |
SONARQUBE_LOG_TO_FILE_DISABLED | When set to true, disables writing logs to disk entirely. No log files will be created under STORAGE_PATH/logs/. Useful in containerized or ephemeral environments where file logging is undesirable. Default: false. |
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 itanalyze_code_snippet: filePath is required and fileContent is not used — the server resolves the file the same wayBy default, only important toolsets are enabled to reduce context overhead. You can enable additional toolsets as needed.
| Environment variable | Description |
|---|---|
SONARQUBE_TOOLSETS | Comma-separated list of toolsets to enable. When set, only these toolsets will be available. If not set, default important toolsets are enabled (analysis, ide, issues, projects, quality-gates, rules, duplications, measures, security-hotspots, dependency-risks, coverage, cag). Note: The projects toolset is always enabled as it's required to find project keys for other operations. Vortex context tools (deprecated name: Context Augmentation/CAG) and Vortex analysis tools (deprecated name: Advanced Analysis/A3S) are only available in stdio mode and share a single combined organization entitlement — an org must be entitled to both to use either. On SonarQube Server, stdio lists Vortex context and run_advanced_code_analysis when both the CAG and A3S hubs are entitled. Prefer the unified vortex toolset key. The deprecated cag and analysis keys still work; a startup warning and a deprecation note in the server instructions are emitted when they are used without vortex. In Streamable HTTP mode, clients can send a SONARQUBE_TOOLSETS HTTP header to narrow this further per-request, but cannot enable toolsets beyond what the server was launched with (see Streamable HTTP transport below). |
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. In Streamable HTTP mode, clients can send a SONARQUBE_READ_ONLY HTTP header to further restrict individual requests to read-only, but cannot lift a server-level read-only restriction (see Streamable HTTP transport below). |
| Toolset | Key | Description |
|---|---|---|
| Analysis | analysis | Code analysis tools (local analysis via analyze_code_snippet, deprecated in favor of analyze_file_list/Vortex analysis) |
| IDE | ide | SonarQube for IDE bridge tools (file analysis, automatic analysis toggle) — currently also included in analysis |
| Issues | issues | Search and manage SonarQube issues |
| Security Hotspots | security-hotspots | Search and review Security Hotspots |
| 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 |
| Duplications | duplications | Find code duplications across projects |
| 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) |
| Coverage | coverage | Test coverage analysis and improvement tools |
| Vortex Context | cag | Vortex context tools — stdio only. Deprecated in favor of vortex (old name: Context Augmentation/CAG) |
| Vortex | vortex | Unified, recommended toolset surfacing both Vortex context and Vortex analysis tools under one name (stdio only; Cloud needs combined org entitlement; Server needs both hubs entitled) |
| Agentic Readiness | agentic-readiness | Agentic Readiness Assessment tools (SonarQube Cloud, requires org entitlement) |
Enable analysis, issues, and quality gates toolsets (using Docker with SonarQube Cloud):
docker run --init --pull=always -i --rm \
-e SONARQUBE_TOKEN="<token>" \
-e SONARQUBE_ORG="<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="<token>" \
-e SONARQUBE_ORG="<org>" \
-e SONARQUBE_READ_ONLY="true" \
sonarsource/sonarqube-mcp
To enable full functionality, the following environment variables must be set before starting the server:
| Environment variable | Description | Required |
|---|---|---|
SONARQUBE_TOKEN | Your SonarQube Cloud token | Yes |
SONARQUBE_ORG | Your SonarQube Cloud organization key | Yes |
SONARQUBE_URL | Custom SonarQube Cloud URL (defaults to https://sonarcloud.io). Use this for SonarQube Cloud US: https://sonarqube.us | No |
Examples:
SONARQUBE_TOKEN and SONARQUBE_ORG are neededSONARQUBE_TOKEN, SONARQUBE_ORG, and SONARQUBE_URL=https://sonarqube.us| Environment variable | Description | Required |
|---|---|---|
SONARQUBE_TOKEN | Your SonarQube Server USER token | Yes |
SONARQUBE_URL | Your SonarQube Server URL | Yes |
⚠️ 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_ORGdetermines whether you're connecting to SonarQube Cloud or Server. IfSONARQUBE_ORGis set, SonarQube Cloud is used; otherwise, SonarQube Server is used.
The MCP specification defines two transport mechanisms: Stdio and Streamable HTTP. The SonarQube MCP Server supports both:
| MCP transport | Server mode | Typical use |
|---|---|---|
| Stdio | Default (no SONARQUBE_TRANSPORT) | Local MCP clients that launch the server as a subprocess (Cursor, Claude Code, VS Code, etc.) |
| Streamable HTTP | SONARQUBE_TRANSPORT=http or https | Remote or multi-user deployments; clients connect to /mcp over HTTP(S) (e.g. Windsurf with a self-hosted server URL) |
Note: Streamable HTTP is the current MCP network transport. The older SSE-only HTTP transport from earlier MCP versions is deprecated and not supported.
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": "<your-token>",
"SONARQUBE_ORG": "<your-org>"
}
}
}
}
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.
| Environment variable | Description | Default |
|---|---|---|
SONARQUBE_TRANSPORT | Set to http to enable Streamable 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 |
SONARQUBE_HTTP_ALLOWED_ORIGINS | Comma-separated browser origins allowed for CORS (e.g. https://my-app.example.com) | Not set |
SONARQUBE_MCP_IN_CONTAINER | Set to true when running inside a container. The official Docker image sets this automatically; set it yourself when using other OCI runtimes (Podman, Kubernetes, Nomad, etc.). | false |
Note: In Streamable HTTP mode (HTTP or HTTPS), the server is stateless — each client request must include an Authorization: Bearer <token> header carrying the user's own SonarQube token. For SonarQube Cloud, the organization is resolved as follows:
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.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_TOKENrequest header is still accepted for backward compatibility but will be removed in a future version. Migrate toAuthorization: Bearer <token>.
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.
| Environment variable | Description | Default |
|---|---|---|
SONARQUBE_TRANSPORT | Set to https to enable Streamable HTTP transport over TLS | 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 |
SONARQUBE_HTTP_ALLOWED_ORIGINS | Comma-separated browser origins allowed for CORS (e.g. https://my-app.example.com) | Not set |
SONARQUBE_MCP_IN_CONTAINER | Set to true when running inside a container. The official Docker image sets this automatically; set it yourself when using other OCI runtimes (Podman, Kubernetes, Nomad, etc.). | false |
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:
Note: When running in a container, set
SONARQUBE_HTTP_HOST=0.0.0.0so the container listens on all interfaces and the runtime's port mapping works, and setSONARQUBE_MCP_IN_CONTAINER=trueto 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.0only 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="<init-token>" \
-e SONARQUBE_ORG="<your-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="<init-token>" \
-e SONARQUBE_ORG="<your-org>" \
sonarsource/sonarqube-mcp
Client Configuration (SonarQube Cloud):
{
"mcpServers": {
"sonarqube-https": {
"url": "https://your-server:8443/mcp",
"headers": {
"Authorization": "Bearer <your-token>",
"SONARQUBE_ORG": "<your-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 <your-token>",
"SONARQUBE_TOOLSETS": "issues,quality-gates",
"SONARQUBE_READ_ONLY": "true"
}
}
}
}
Note:
SONARQUBE_TOOLSETSandSONARQUBE_READ_ONLYare 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.
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.
| Endpoint | Method | Description | Example response |
|---|---|---|---|
/health | GET | Liveness probe. Returns 200 OK with an empty body once the server is accepting requests. | (empty body) |
/info | GET | Returns the MCP server version as JSON. Useful for verifying the deployed server version. | {"version":"1.16.0"} |
These endpoints are not available when running with the Stdio transport.
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.
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="<token>" \
-e SONARQUBE_URL="<url>" \
sonarsource/sonarqube-mcp
The container supports the following certificate formats:
.crt files (PEM or DER encoded).pem files (PEM encoded)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": "<token>",
"SONARQUBE_URL": "<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=<passphrase>. It is added on top of the default trusted certificates.
The SonarQube MCP Server supports HTTP and SOCKS5 proxies through standard Java proxy system properties.
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|*.internal.com |
HTTP/HTTPS Proxy Authentication:
| 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 |
SOCKS5 proxies are supported.
| Property | Description | Default | Example |
|---|---|---|---|
socksProxyHost | SOCKS5 proxy hostname | — | localhost |
socksProxyPort | SOCKS5 proxy port | 1080 | 1080 |
java.net.socks.username | SOCKS5 username (if auth required) | — | myuser |
java.net.socks.password | SOCKS5 password (if auth required) | — | mypassword |
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.
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=<passphrase>" \
-e SONARQUBE_TOKEN="<token>" \
-e SONARQUBE_URL="<url>" \
sonarsource/sonarqube-mcp
Note: The certificate file must be readable by the container process. Check and fix permissions if needed:
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.
{
"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=<passphrase>",
"SONARQUBE_TOKEN": "<token>",
"SONARQUBE_URL": "<url>"
}
}
}
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=<passphrase> \
-jar <path_to_sonarqube_mcp_server_jar>
Omit -Djavax.net.ssl.keyStorePassword if the keystore has no passphrase.
{
"sonarqube": {
"command": "java",
"args": [
"-Djavax.net.ssl.keyStore=/path/to/client.p12",
"-Djavax.net.ssl.keyStoreType=PKCS12",
"-Djavax.net.ssl.keyStorePassword=<passphrase>",
"-jar",
"<path_to_sonarqube_mcp_server_jar>"
],
"env": {
"SONARQUBE_TOKEN": "<token>",
"SONARQUBE_URL": "<url>"
}
}
}
Note: PEM certificate and key files (separate
.crt/.keyfiles) must be converted to PKCS12 format first. Useopenssl pkcs12 -export -in client.crt -inkey client.key -out client.p12to convert them.
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_snippetwill be removed in a future release. Connect SonarQube for IDE to useanalyze_file_list, or enable Vortex analysis for your organization to userun_advanced_code_analysis(see below).
Usage:
filePath (project-relative) — the server reads the file directly, keeping file content out of the agent context windowfileContent for full file analysis (reports all issues)codeSnippet to filter results - only issues within the snippet will be reported (snippet location auto-detected)Parameters:
projectKey - The SonarQube project key - Required String (Ignored when SONARQUBE_PROJECT_KEY is defined)filePath - Project-relative path of the file to analyze (e.g., src/main/java/MyClass.java). Used when the workspace is mounted at /app/mcp-workspace - StringfileContent - Complete file content as a string. Required when workspace is not mounted - StringcodeSnippet - Code snippet to filter issues (must match content in fileContent) - Stringlanguage - Language of the code (e.g., 'java', 'python', 'js', 'ts', 'tsx', 'jsx') - Stringscope - Scope of the file: MAIN or TEST (default: MAIN) - StringSupported 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.
file_absolute_paths - List of absolute file paths to analyze - Required String[]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.
enabled - Enable or disable the automatic analysis - Required BooleanOn 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
projectKey - The key of the project - Required String (Ignored when SONARQUBE_PROJECT_KEY is defined)branch - Branch name used to retrieve the latest analysis context - Required StringfilePath - Project-relative path of the file to analyze (e.g., src/main/java/MyClass.java). - Required StringfileScope - Defines in which scope the file originates from: 'MAIN' or 'TEST' (default: MAIN) - Stringsearch_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 - StringpullRequest - Optional pull request key/ID. Use list_pull_requests to discover valid keys - StringmaxCoverage - Maximum coverage threshold (0-100). Only return files with coverage <= this value - NumberpageIndex - Page index (1-based, default: 1) - NumberpageSize - Page size (default: 100, max: 500) - Numberget_file_coverage_details - Get line-by-line coverage information for a specific file, including which exact lines are uncovered and which have partially covered branches. This tool helps identify precisely where to add test coverage. Use after identifying files with low coverage via search_files_by_coverage.
key - File key (e.g. my_project:src/foo/Bar.java) - Required Stringbranch - Optional branch name for branch-based analysis. Use list_branches to discover valid names - StringpullRequest - Optional pull request key/ID. Use list_pull_requests to discover valid keys - Stringfrom - First line to analyze (1-based, default: 1) - Numberto - Last line to analyze (inclusive). If not specified, all lines are returned - NumberNote: Dependency risks are only available when connecting to SonarQube Server 2025.4 Enterprise or higher with SonarQube Advanced Security enabled.
projectKey - Project key - Required String (Ignored when SONARQUBE_PROJECT_KEY is defined)branch - Optional branch name for branch-based analysis. Use list_branches to discover valid names - StringpullRequest - Optional pull request key/ID. Use list_pull_requests to discover valid keys - StringpageIndex - Optional page index (1-based, default: 1) - IntegerpageSize - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - IntegerNote: Enterprises are only available when connecting to SonarQube Cloud.
enterpriseKey - Optional enterprise key to filter results - Stringchange_sonar_issue_status - Change the status of a SonarQube issue to "accept", "falsepositive" or to "reopen" an issue.
key - Issue key - Required Stringstatus - New issue's status - Required Enum {"accept", "falsepositive", "reopen"}comment - Optional comment explaining the status change - Stringsearch_sonar_issues_in_projects - Search for SonarQube issues in my organization's projects.
projectKeys - Optional list of SonarQube project keys - String[]branch - Optional branch name for branch-based analysis. Use list_branches to discover valid names - StringpullRequest - Optional pull request key/ID. Use list_pull_requests to discover valid keys - Stringseverities - Optional list of severities to filter by. Possible values: INFO, LOW, MEDIUM, HIGH, BLOCKER - String[]impactSoftwareQualities - Optional list of software qualities to filter by. Possible values: MAINTAINABILITY, RELIABILITY, SECURITY - String[]issueStatuses - Optional list of issue statuses to filter by. Possible values: OPEN, CONFIRMED, FALSE_POSITIVE, ACCEPTED, FIXED, IN_SANDBOX - String[]tags - Optional list of issue tags to filter by. Tags are lowercase - String[]inNewCodePeriod - Only return issues in the new code period. Requires exactly one entry across projectKeys and files - BooleanissueKey - Optional issue key to fetch a specific issue - StringpageIndex - Optional 1-based page index (default: 1) - IntegerpageSize - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - Integersearch_security_hotspots - Search for Security Hotspots in a SonarQube project.
projectKey - Project or application key - Required String (Ignored when SONARQUBE_PROJECT_KEY is defined)hotspotKeys - Comma-separated list of specific Security Hotspot keys to retrieve - String[]branch - Optional branch name for branch-based analysis. Use list_branches to discover valid names - StringpullRequest - Optional pull request key/ID. Use list_pull_requests to discover valid keys - Stringfiles - Optional list of file paths to filter - String[]status - Optional status filter: TO_REVIEW, REVIEWED - Stringresolution - Optional resolution filter: FIXED, SAFE, ACKNOWLEDGED - StringsinceLeakPeriod - Filter hotspots created since the leak period (new code) - BooleanonlyMine - Show only hotspots assigned to me - BooleanpageIndex - Optional 1-based page index (default: 1) - IntegerpageSize - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - Integershow_security_hotspot - Get detailed information about a specific Security Hotspot, including rule details, code context, flows, and comments.
hotspotKey - Security Hotspot key - Required Stringchange_security_hotspot_status - Review a Security Hotspot by changing its status. When marking as REVIEWED, you must specify a resolution (FIXED, SAFE, or ACKNOWLEDGED).
hotspotKey - Security Hotspot key - Required Stringstatus - New status - Required Enum {"TO_REVIEW", "REVIEWED"}resolution - Resolution when status is REVIEWED - Enum {"FIXED", "SAFE", "ACKNOWLEDGED"}comment - Optional review comment - Stringq - Optional pattern to match language keys/names against - StringSONARQUBE_TOKEN*secretYour SonarQube USER token
SONARQUBE_ORGsecretYour SonarQube Cloud organization key (if using SonarQube Cloud)
SONARQUBE_URLsecretYour SonarQube Server URL (if using SonarQube Server)