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 <your-sonarqube-url>/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

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

Warning: The SonarQube Agentic Analysis and Sonar Context Augmentation services require file system access and don't work with the SonarQube Server-hosted MCP server. See the Agentic Analysis and Context Augmentation pages for instructions to set up those analysis services.

Compatibility

SonarQube Server version	Compatible MCP Server version
2026.3	1.18.1.2664

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 from ZIP file

See the SonarQube Server documentation for instructions to install SonarQube Server from a ZIP file.

Configure MCP properties

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.

More information about available properties can be found on 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:

https://binaries.sonarsource.com/Distribution/sonarqube-mcp-server/sonarqube-mcp-server-<YourMCPServerVersion>.jar

Step 2: Create a storage directory

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

mkdir -p ~/.sonarqube-mcp-storage

Step 3: Set environment variables

See the Environment variables page if needed.

# Storage directory created in step 2
export STORAGE_PATH="$HOME/.sonarqube-mcp-storage"

# SonarQube Server URL
export SONARQUBE_URL="http://localhost:9000"

# Transport mode for the MCP server
export SONARQUBE_TRANSPORT="http"

# Host the MCP server binds to: keep 127.0.0.1 for local use
export SONARQUBE_HTTP_HOST="127.0.0.1"

# Port for the MCP HTTP server (default: 8080, range: 1024–65535)
export SONARQUBE_HTTP_PORT="8080"

Step 4: Start the MCP server

java -jar /absolute/path/to/sonarqube-mcp-server-<YourMCPServerVersion>.jar

Optional: Script for steps 1–4

Create a file named run-mcp-server.sh:

#!/usr/bin/env bash
set -euo pipefail

MCP_VERSION="${<YourMCPServerVersion>}"

export STORAGE_PATH="${STORAGE_PATH:-$HOME/.sonarqube-mcp-storage}"
mkdir -p "$STORAGE_PATH"

export SONARQUBE_URL="${SONARQUBE_URL:-http://localhost:9000}"
export SONARQUBE_TRANSPORT="${SONARQUBE_TRANSPORT:-http}"
export SONARQUBE_HTTP_HOST="${SONARQUBE_HTTP_HOST:-127.0.0.1}"
export SONARQUBE_HTTP_PORT="${SONARQUBE_HTTP_PORT:-8080}"

JAR_NAME="sonarqube-mcp-server-${MCP_VERSION}.jar"
MCP_JAR_URL="https://binaries.sonarsource.com/Distribution/sonarqube-mcp-server/${JAR_NAME}"

echo "Downloading SonarQube MCP Server ${MCP_VERSION}..."
curl -fL "$MCP_JAR_URL" -o "$JAR_NAME"

echo "Starting SonarQube MCP Server from $JAR_NAME"
echo "HTTP endpoint: http://$SONARQUBE_HTTP_HOST:$SONARQUBE_HTTP_PORT/mcp"

java -jar "$JAR_NAME"

Then make the script executable and run it:

chmod +x run-mcp-server.sh
./run-mcp-server.sh

Install from Docker image

See the SonarQube Server documentation for instructions to install SonarQube Server when using Docker.

Prerequisites

• SonarQube Server 2026.3 or later

• Docker / Docker Compose

• Check the MCP server version compatible with your SonarQube Server version

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

services:
  sonarqube:
    image: sonarqube:${SONARQUBE_VERSION:-2026.3.0-developer}
    hostname: sonarqube
    container_name: sonarqube
    read_only: true
    depends_on:
      db:
        condition: service_healthy
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
      SONAR_MCP_ENABLED: "true"
      SONAR_MCP_SERVERURL: "http://mcp:8080"
      SONAR_MCP_HEALTHCHECKINTERVAL: "30"
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_temp:/opt/sonarqube/temp
    tmpfs:
      - /tmp:size=256M,mode=1777
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:9000/api/system/status | grep -q '\"status\":\"UP\"'"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 120s
    ports:
      - "9000:9000"
    networks:
      - sonarnet

  mcp:
    image: sonarsource/sonarqube-mcp:${MCP_VERSION:-1.18.1.2664}
    hostname: mcp
    container_name: sonarqube-mcp
    depends_on:
      sonarqube:
        condition: service_healthy
    environment:
      STORAGE_PATH: /data
      SONARQUBE_URL: http://sonarqube:9000
      SONARQUBE_HTTP_HOST: mcp
      SONARQUBE_HTTP_PORT: 8080
      SONARQUBE_TRANSPORT: http
    volumes:
      - mcp_data:/data
    ports:
      - "8080:8080"
    networks:
      - sonarnet

  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    hostname: postgresql
    container_name: postgresql
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgresql:/var/lib/postgresql
    networks:
      - sonarnet

volumes:
  sonarqube_data:
  sonarqube_temp:
  sonarqube_extensions:
  sonarqube_logs:
  postgresql:
  mcp_data:

networks:
  sonarnet:
    driver: bridge

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

See also Environment variables.

Option 2: Full Docker Compose (Data Center edition)

See an example on GitHub.

services:
  sonarqube:
    deploy:
      replicas: 2
    healthcheck:
      test: curl -s http://localhost:9000/api/system/status | grep -q -e '"status":"UP"' -e '"status":"DB_MIGRATION_NEEDED"' -e '"status":"DB_MIGRATION_RUNNING"'
      interval: 25s
      timeout: 1s
      retries: 3
      start_period: 240s
    image: sonarqube:${SONARQUBE_VERSION:-2026.3.0-datacenter-app}
    read_only: true
    depends_on:
      search-1:
        condition: service_healthy
      search-2:
| 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                                           |
      db:
        condition: service_healthy
    networks:
      - ${NETWORK_TYPE:-ipv4}
    cpus: 0.5
    mem_limit: 4096M
    mem_reservation: 4096M
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
      SONAR_WEB_PORT: 9000
      SONAR_CLUSTER_SEARCH_HOSTS: "search-1,search-2,search-3"
      SONAR_CLUSTER_HOSTS: "sonarqube"
      SONAR_CLUSTER_KUBERNETES: true
      SONAR_AUTH_JWTBASE64HS256SECRET: "dZ0EB0KxnF++nr5+4vfTCaun/eWbv6gOoXodiAMqcFo="
      SONAR_MCP_ENABLED: "true"
      SONAR_MCP_SERVERURL: "http://mcp:8080"
      SONAR_MCP_HEALTHCHECKINTERVAL: "30"
    volumes:
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_temp:/opt/sonarqube/temp
      - /opt/sonarqube/data

  search-1:
    image: sonarqube:${SONARQUBE_VERSION:-2026.3.0-datacenter-search}
    read_only: true
    hostname: "search-1"
    cpus: 0.5
    mem_limit: 3072M
    mem_reservation: 3072M
    depends_on:
      db:
        condition: service_healthy
    networks:
      - ${NETWORK_TYPE:-ipv4}
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
      SONAR_CLUSTER_ES_HOSTS: "search-1,search-2,search-3"
      SONAR_CLUSTER_NODE_NAME: "search-1"
    volumes:
      - search_data-1:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs
      - search_temp-1:/opt/sonarqube/temp
      - search_logs-1:/opt/sonarqube/logs
    tmpfs:
      - /tmp:size=256M,mode=1777
    healthcheck:
      test: curl -s "http://$$SONAR_CLUSTER_NODE_NAME:9001/_cluster/health?wait_for_status=yellow&timeout=50s" | grep -q -e '"status":"green"' -e '"status":"yellow"'; if [ $? -eq 0 ]; then exit 0; else exit 1; fi
      interval: 25s
      timeout: 1s
      retries: 3
      start_period: 55s

  search-2:
    image: sonarqube:${SONARQUBE_VERSION:-2026.3.0-datacenter-search}
    read_only: true
    hostname: "search-2"
    cpus: 0.5
    mem_limit: 3072M
    mem_reservation: 3072M
    depends_on:
      db:
        condition: service_healthy
    networks:
      - ${NETWORK_TYPE:-ipv4}
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
      SONAR_CLUSTER_ES_HOSTS: "search-1,search-2,search-3"
      SONAR_CLUSTER_NODE_NAME: "search-2"
    volumes:
      - search_data-2:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs
      - search_temp-2:/opt/sonarqube/temp
      - search_logs-2:/opt/sonarqube/logs
    tmpfs:
      - /tmp:size=256M,mode=1777
    healthcheck:
      test: curl -s "http://$$SONAR_CLUSTER_NODE_NAME:9001/_cluster/health?wait_for_status=yellow&timeout=50s" | grep -q -e '"status":"green"' -e '"status":"yellow"'; if [ $? -eq 0 ]; then exit 0; else exit 1; fi
      interval: 25s
      timeout: 1s
      retries: 3
      start_period: 55s

  search-3:
    image: sonarqube:${SONARQUBE_VERSION:-2026.3.0-datacenter-search}
    read_only: true
    hostname: "search-3"
    cpus: 0.5
    mem_limit: 3072M
    mem_reservation: 3072M
    depends_on:
      db:
        condition: service_healthy
    networks:
      - ${NETWORK_TYPE:-ipv4}
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
      SONAR_CLUSTER_ES_HOSTS: "search-1,search-2,search-3"
      SONAR_CLUSTER_NODE_NAME: "search-3"
    volumes:
      - search_data-3:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs
      - search_temp-3:/opt/sonarqube/temp
      - search_logs-3:/opt/sonarqube/logs
    tmpfs:
      - /tmp:size=256M,mode=1777
    healthcheck:
      test: curl -s "http://$$SONAR_CLUSTER_NODE_NAME:9001/_cluster/health?wait_for_status=yellow&timeout=50s" | grep -q -e '"status":"green"' -e '"status":"yellow"'; if [ $? -eq 0 ]; then exit 0; else exit 1; fi
      interval: 25s
      timeout: 1s
      retries: 3
      start_period: 55s

  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - ${NETWORK_TYPE:-ipv4}
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgresql:/var/lib/postgresql

  mcp:
    image: sonarsource/sonarqube-mcp:${MCP_VERSION:-1.18.1.2664}
    hostname: mcp
    container_name: sonarqube-mcp
    depends_on:
      sonarqube:
        condition: service_healthy
    environment:
      STORAGE_PATH: /data
      SONARQUBE_URL: http://sonarqube:9000
      SONARQUBE_HTTP_HOST: mcp
      SONARQUBE_HTTP_PORT: 8080
      SONARQUBE_TRANSPORT: http
    volumes:
      - mcp_data:/data
    ports:
      - "8080:8080"
    networks:
      - ${NETWORK_TYPE:-ipv4}

networks:
  ipv4:
    driver: bridge
    enable_ipv6: false
  dual:
    driver: bridge
   See the full list of `mcp.*` values in the [SonarQube Helm chart README](https://github.com/SonarSource/helm-chart-sonarqube/blob/master/charts/sonarqube/README.md#mcp-model-context-protocol).
    ipam:
      config:
        - subnet: "192.168.3.0/24"
          gateway: "192.168.3.1"
        - subnet: "2001:db8:3::/64"
          gateway: "2001:db8:3::1"

volumes:
  sonarqube_extensions:
  sonarqube_logs:
  sonarqube_temp:
  search_data-1:
  search_data-2:
  search_data-3:
  search_temp-1:
  search_temp-2:
  search_temp-3:
  search_logs-1:
  search_logs-2:
  search_logs-3:
  postgresql:
  mcp_data:

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:

sonar.mcp.enabled=true
sonar.mcp.serverUrl=http://<mcp-host>:8080
# Optional: sonar.mcp.healthCheckInterval=30

Then restart SonarQube Server for the changes to take effect.

Step 2: Start the MCP container

docker run -d \
  --name sonarqube-mcp \
  -e STORAGE_PATH=/data \
  -e SONARQUBE_URL=http://<sonarqube-host>:9000 \
  -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  -e SONARQUBE_HTTP_PORT=8080 \
  -e SONARQUBE_TRANSPORT=http \
  -v mcp_data:/data \
  -p 8080:8080 \
  sonarsource/sonarqube-mcp:${MCP_VERSION:-1.18.1.2664}

Replace <sonarqube-host> 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:

   helm repo add sonarqube https://SonarSource.github.io/helm-chart-sonarqube
   helm repo update

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:

   mcp:
     enabled: true

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

3. Deploy or upgrade your SonarQube Helm chart:

   helm upgrade --install -n sonarqube sonarqube sonarqube/sonarqube

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:

   kubectl create secret generic mcp-ca-cert \
     --from-file=mcp-ca.crt=/path/to/ca.pem \
     -n <namespace>

2. Reference it in your values:

   mcp:
     tls:
       enabled: true
       keystoreSecretName: mcp-keystore-secret
       keystoreSecretKey: keystore.p12
       passwordSecretName: mcp-keystore-password
       passwordSecretKey: password
       keystoreType: PKCS12
   
   caCerts:
     enabled: true
     secret: mcp-ca-cert

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:

   helm repo add sonarqube https://SonarSource.github.io/helm-chart-sonarqube
   helm repo update

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:

   mcp:
     enabled: true

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

3. Deploy or upgrade your SonarQube DCE Helm chart:

   helm upgrade --install -n sonarqube sonarqube sonarqube/sonarqube-dce

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:

   kubectl create secret generic mcp-ca-cert \
     --from-file=mcp-ca.crt=/path/to/ca.pem \
     -n <namespace>

2. Reference it in your values:

   mcp:
     tls:
       enabled: true
       keystoreSecretName: mcp-keystore-secret
       keystoreSecretKey: keystore.p12
       passwordSecretName: mcp-keystore-password
       passwordSecretKey: password
       keystoreType: PKCS12
   
   caCerts:
     enabled: true
     secret: mcp-ca-cert

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.

2. Find your environment variables.

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

3. Choose a hosting method:

   • Select Remote server (HTTP).

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

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

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