For the complete documentation index, see llms.txt. This page is also available as Markdown.

SonarQube Server-hosted

Install and configure the SonarQube MCP Server extension on SonarQube Server.

Overview

The SonarQube MCP Server can be installed as an extension on SonarQube Server. Once installed, SonarQube Server acts as a proxy and exposes the MCP server's tools at <YourSonarQubeURL>/mcp. Your AI agent connects to that single endpoint: no separate MCP server URL to manage.

Note: The SonarQube Server MCP extension is available on all commercial editions: Developer, Enterprise, and Data Center Edition.

Prerequisites

  • SonarQube Server 2026.3 or later

Warning: Sonar Vortex's agentic analysis and context augmentation features require file system access and don't work with the SonarQube Server-hosted MCP server. To set them up, the recommended methods are the SonarQube plugin or SonarQube CLI. See the Make your agent verify its code and Add context to generate better code pages.

Compatibility

SonarQube Server version
Compatible MCP Server version

2026.3

1.18.1.2664

Always set MCP_VERSION to the full 4-part version from the compatibility table (for example, use 1.18.1.2664 with SonarQube Server 2026.3). Only full 4-part tags are published to Docker Hub; 3-part tags like 1.18.1 don't exist.

Install the MCP server

Once the SonarQube MCP Server extension is installed, SonarQube Server acts as a proxy and exposes the MCP server's tools at /mcp. Your AI coding agent connects to that single endpoint. There's no separate MCP server URL to manage.

Select the installation method that matches how you run SonarQube Server.

Install the MCP from ZIP file

Prerequisites

  • SonarQube Server 2026.3 or later

  • JDK 21 or later (required to run the MCP server JAR)

  • A compatible MCP server version. See the Compatibility table for reference.

Configure MCP properties in your SonarQube Server instance

In your conf/sonar.properties file, set the following properties:

  • sonar.mcp.enabled: enables or disables the MCP proxy (default: true)

  • sonar.mcp.serverUrl: the URL where the MCP server will be running

  • sonar.mcp.healthCheckInterval (optional): health check interval (default: 30s)

Then restart SonarQube for the changes to take effect.

Find the full list of available properties in the Configuration reference section.

Start the MCP server

Step 1: Download the JAR

Download the MCP server JAR. Check the compatible version for your SonarQube Server version in the Compatibility table. All versions of the SonarQube MCP Server are available on the binaries page, or add your version into the code sample below to download directly:

Step 2: Create a storage directory

The MCP server needs a writable directory to store its files (logs, plugins, tmp, etc.):

Step 3: Set environment variables

See the Environment variables page if needed.

Step 4: Run the MCP server

Optional: Script for steps 1–4

Group steps 1–4 in a script named run-mcp-server.sh:

Then make the script executable and run it:

Step 5: Run as a service (optional)

On Linux with systemd

Install the MCP server as a service on a Unix system using systemd; you cannot run it as root. To install using systemd, create a dedicated account for running the MCP server. Here's an example:

  • The Java Virtual Machine is installed in /opt/java/

  • The MCP server JAR has been downloaded into /opt/sonarqube-mcp/

Then create the file /etc/systemd/system/sonarqube-mcp.service based on the following:

Note:

  • Because the sonarqube-mcp-server jar name ends with the version of the MCP server, you will need to adjust the ExecStart command accordingly on install and at each upgrade.

  • All MCP server directories should be owned by the sonarqube user.

  • If you have multiple Java versions, you will need to modify the java path in the ExecStart command. This also means SONAR_JAVA_PATH will not work with the MCP server running as a service.

Once your sonarqube-mcp.service file is created and properly configured, run:

On Windows

Use the Windows Service Control Manager or a tool such as NSSM to register the MCP server JAR as a Windows service. Set the environment variables from Step 3 in the service configuration.

Install the MCP from Docker image

Prerequisites

Note: The examples below use Docker Compose. You can replace any of them with equivalent plain docker run commands if you prefer.

Option 1: Full Docker Compose (Developer and Enterprise edition)

Add an mcp service alongside your sonarqube service and pass the MCP connection properties as environment variables on the SonarQube Server container. The example below uses the Developer edition — replace the tag developer with enterprise to deploy the Enterprise edition instead.

See an example on GitHub.

For SonarQube MCP environment variables, see the Configuration reference section.

MCP container environment variables:

Variable
Example
Description

STORAGE_PATH

/data

Writable directory for MCP logs, plugins, and temp files

SONARQUBE_URL

mcp

Host the MCP server binds to

SONARQUBE_HTTP_PORT

8080

Port the MCP server listens on

SONARQUBE_TRANSPORT

http

Transport mode

Option 2: Full Docker Compose (Data Center edition)

See an example on GitHub.

MCP container environment variables:

Variable
Example
Description

STORAGE_PATH

/data

Writable directory for MCP logs, plugins, and temp files

SONARQUBE_URL

http://sonarqube:9000

The URL of the SonarQube Server instance the MCP server connects to

SONARQUBE_HTTP_PORT

8080

Port the MCP server listens on

SONARQUBE_TRANSPORT

http

Transport mode

Option 3: Hybrid (SonarQube Server from ZIP + MCP as Docker container)

Use this option when SonarQube Server is installed from a ZIP archive and you want to run the MCP server as a Docker container.

Step 1: Configure SonarQube Server

In conf/sonar.properties, set:

Then restart SonarQube Server for the changes to take effect.

Step 2: Start the MCP container

Replace <YourSonarQubeHostname> with the hostname or IP address reachable from within the container.

Install on Kubernetes or OpenShift

See the SonarQube Server documentation for instructions to install SonarQube Server on Kubernetes or OpenShift.

  1. Add the SonarQube Helm chart repository:

  2. Enable MCP in your Helm values file. When mcp.enabled is set to true, the chart automatically deploys the MCP server as a separate pod alongside SonarQube and wires both services together via SONAR_MCP_ENABLED and SONAR_MCP_SERVERURL:

    See the full list of mcp.* values in the SonarQube Helm chart README.

  3. Deploy or upgrade your SonarQube Helm chart:

Optional TLS encrypted communication

To enable an extra level of security, set mcp.tls.enabled to true. The MCP server starts in HTTPS mode using the keystore from mcp.tls.keystoreSecretName. Application nodes connect to it over https://.

If the keystore uses a self-signed certificate, SonarQube's JVM will reject the connection unless the CA certificate is trusted. Use the caCerts feature to import it into SonarQube's JVM truststore:

  1. Create a Secret containing the CA certificate in PEM format:

  2. Reference it in your values:

Install on Kubernetes or OpenShift for Data Center edition

See the SonarQube Server documentation for instructions to install SonarQube Server on Kubernetes or OpenShift for Data Center edition.

  1. Add the SonarQube Helm chart repository:

  2. Enable MCP in your Helm values file. When mcp.enabled is set to true, the chart automatically deploys the MCP server as a separate pod alongside SonarQube and wires both services together via SONAR_MCP_ENABLED and SONAR_MCP_SERVERURL:

    See the full list of mcp.* values in the SonarQube DCE Helm chart README.

  3. Deploy or upgrade your SonarQube DCE Helm chart:

Optional TLS encrypted communication

To enable an extra level of security, set mcp.tls.enabled to true. The MCP server starts in HTTPS mode using the keystore from mcp.tls.keystoreSecretName. Application nodes connect to it over https://.

If the keystore uses a self-signed certificate, SonarQube's JVM will reject the connection unless the CA certificate is trusted. Use the caCerts feature to import it into SonarQube's JVM truststore:

  1. Create a Secret containing the CA certificate in PEM format:

  2. Reference it in your values:

Configuration reference

The following properties configure the MCP proxy on SonarQube Server. Set them in conf/sonar.properties or as environment variables on the SonarQube container.

System property (sonar property and ENVIRONMENT_VARIABLE)
Description

sonar.mcp.enabled SONAR_MCP_ENABLED

Enables or disables the MCP proxy. (default: true)

sonar.mcp.serverUrl SONAR_MCP_SERVERURL

The URL where the MCP server will be running.

sonar.mcp.healthCheckInterval SONAR_MCP_HEALTHCHECKINTERVAL

Health check interval. (default: 30s) (optional)

Connect your AI agent

Once the MCP server extension is running, configure your AI agent to connect to it.

Step 1: Generate a user token

In SonarQube Server, go to My Account > Security and generate a user token.

Step 2: Configure your agent

Use the official SonarQube MCP Server configuration generator to get a configuration snippet for your setup:

  1. Identify your target MCP client.

    • Select SonarQube Server as your instance.

    • Use environment variable substitution to pass your token, or enter your SonarQube Server user token directly in the User token (optional) field.

  2. Choose a hosting method:

    • Select Remote server (HTTP).

    • Fill the full server URL with https://<YourSonarQubeURL>/mcp. Don't add a trailing slash.

  3. Copy the configuration and paste it into your terminal.

    • Optional: To make the MCP server available globally and not only for the repo where the command has been run, append --scope user to your CLI command.

    • Optional: Verify that the SonarQube entry has been added to your agent configuration file with your user token and the new URL.

  4. Restart your agent after saving the configuration and run /mcp to verify it's working.

Check the status

After installation, verify the extension is running correctly. In SonarQube Server, go to Administration > System info > System > MCP and check the Enabled and Healthy statuses.

Last updated

Was this helpful?