> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-mcp-server/reference/environment-variables.md). # Environment variables Environment variables reference for the SonarQube MCP Server. The environment variables you need depend on your Sonar product and deployment type. Variables are grouped into four main categories based on your environment. ## Common variables *Common variables* configure how the server connects and authenticates. Requirements differ by [transport mode](/sonarqube-mcp-server/setup/self-hosted.md); see each variable for details. ### SONARQUBE\_ORG For SonarQube Cloud only. Optional organization [key](https://sonarcloud.io/account/organizations). When set, it fixes the Cloud organization. In stdio mode, a token without [`SONARQUBE_URL`](#sonarqube_url) connects to SonarQube Cloud (`https://sonarcloud.io`). Set `SONARQUBE_ORG` to fix one organization for the process. Organization-aware tools then omit the `organization` argument, and a call that passes it is rejected. This works the same way as `projectKey` when `SONARQUBE_PROJECT_KEY` is set. Leave `SONARQUBE_ORG` unset to choose an organization on each tool call. If your token belongs to exactly one organization, the server selects it at startup and keeps it as the default. Zero or multiple organizations leave the organization unresolved. Call [`list_organizations`](/sonarqube-mcp-server/reference/tools.md#projects), then pass a returned key as `organization`. That argument applies only to the call and does not change the detected default. In Streamable HTTP mode, setting `SONARQUBE_ORG` on the SonarQube MCP Server is deprecated for token requests. If you still set it, the SonarQube MCP Server logs a warning at startup, fixes the organization for every token request, and rejects a client `SONARQUBE_ORG` header and a tool `organization` argument. When you do not set it on the SonarQube MCP Server, an optional client `SONARQUBE_ORG` header fixes the organization for that token request and rejects the tool argument. Without the header, pass `organization` on the tool call. See [Self-hosted setups](/sonarqube-mcp-server/setup/self-hosted.md#remote-server-streamable-http) and [Deprecations and removals](/sonarqube-mcp-server/deprecations-and-removals.md). On the [SonarQube Cloud-hosted MCP server](/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md#sign-in-with-oauth), an OAuth request rejects a `SONARQUBE_ORG` header. Call [`list_organizations`](/sonarqube-mcp-server/reference/tools.md#projects), then pass `organization` on the tool. Self-hosted deployments continue to use SonarQube tokens. ### SONARQUBE\_TOKEN Your SonarQube Cloud token (see [Managing Personal Access Tokens](/sonarqube-cloud/managing-your-account/managing-tokens.md)) or your SonarQube Server token (see [Managing your tokens](/sonarqube-server/2026.1/user-guide/managing-tokens.md)). In stdio mode, set `SONARQUBE_TOKEN` as an environment variable. The server needs it at startup and fails without it. In Streamable HTTP mode, the startup token is optional. Each client sends its own token in the `Authorization: Bearer ` header with every request. On SonarQube Server, set a startup token in HTTP or HTTPS mode to enable snippet analysis. SonarQube Cloud over HTTP or HTTPS does not register analysis tools, even when a startup token is set. > **Deprecation notice (Streamable HTTP transport):** For SonarQube tokens, passing the token via a `SONARQUBE_TOKEN` HTTP header is deprecated. Use the `Authorization: Bearer ` header instead. The [SonarQube Cloud-hosted MCP server](/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md#sign-in-with-oauth) also accepts OAuth sign-in. For stdio transport, `SONARQUBE_TOKEN` as an environment variable is unchanged. See [HTTPS](/sonarqube-mcp-server/setup/self-hosted.md#https-streamable-http-over-tls) for details. ### SONARQUBE\_URL * **SonarQube Server or SonarQube Community Build:** Set to your [Server base URL](/sonarqube-server/2026.1/instance-administration/server-base-url.md). * **SonarQube Cloud, US region:** Set to `https://sonarqube.us`. * **SonarQube Cloud, EU region:** Not required. The default is `https://sonarcloud.io`. A token without `SONARQUBE_URL` connects to SonarQube Cloud. Use SonarQube Server 2025.1 or newer, or SonarQube Community Build 25.1 or newer. The server checks the version at startup. See [Prerequisites](/sonarqube-mcp-server/setup/prerequisites.md). ## Base variables *Base variables* are used when building and running the MCP server locally. The server needs to know how to identify the client and where the local storage location can be found. These variables may or may not be required depending on your configuration. For example, if you're running the container image: | Environment variable | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SONARQUBE\_DEBUG\_ENABLED | When set to `true`, enables debug logging. Debug logs are written to both the log file and STDERR. Default: `false`. Use this variable to troubleshoot connectivity or configuration issues. | | SONARQUBE\_IDE\_PORT | Optional port number between 64120 and 64130 used to connect SonarQube MCP Server with SonarQube for IDE. | | SONARQUBE\_FORCE\_LOCAL\_ANALYSIS | Set to `true` to use `analyze_code_snippet` instead of Vortex analysis on SonarQube Cloud stdio. Default: `false`. See [SONARQUBE\_FORCE\_LOCAL\_ANALYSIS](#sonarqube_force_local_analysis). | | SONARQUBE\_LOG\_TO\_FILE\_DISABLED | When set to `true`, disables writing logs to disk. No log files are created under `STORAGE_PATH/logs/`. Default: `false`. Typical use case: containerized or ephemeral environments where log files on disk are not needed. | | STORAGE\_PATH | An absolute path to a writable directory where SonarQube MCP Server will store its files (e.g., for creation, updates, and persistence). This path is automatically provided when using the container image. | | SONARQUBE\_PROJECT\_KEY | Optional default project key used by all tools that require a project key. When set, the `projectKey` parameter is removed from the schemas of relevant tools. Typical use case: working on a single project. | ### SONARQUBE\_FORCE\_LOCAL\_ANALYSIS Set this to `true` to register `analyze_code_snippet` instead of `run_advanced_code_analysis` on SonarQube Cloud stdio. This includes organizations with an active Vortex subscription, and it applies when SonarQube for IDE is connected. Enable the `analysis` toolset, then restart the server. Default: `false`. This setting has no effect on SonarQube Server or on SonarQube Cloud over HTTP or HTTPS. ## HTTP variables *HTTP variables* are used when multiple clients connect to a shared MCP server over Streamable HTTP. Each client provides its own user token. | Environment variable | Description | Default | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | SONARQUBE\_TRANSPORT | Set to `http` to enable Streamable HTTP transport | not defined (stdio) | | SONARQUBE\_HTTP\_HOST | Host to bind (defaults to localhost for security) | 127.0.0.1 | | SONARQUBE\_HTTP\_PORT | Port number (1024-65535), or `0` for an OS-assigned port | 8080 | | SONARQUBE\_HTTP\_ALLOWED\_ORIGINS | Comma-separated browser origins allowed for CORS (for example, `https://my-app.example.com`) | not defined | | SONARQUBE\_MCP\_IN\_CONTAINER | Set to `true` in custom container images to suppress the startup warning when binding to `0.0.0.0`. Already set in the official image. | false | If needed, information about HTTP and HTTPS [proxy settings](/sonarqube-mcp-server/setup/environment-considerations.md#proxy) is available on the [Environment considerations](/sonarqube-mcp-server/setup/environment-considerations.md) page. ## HTTPS variables *HTTPS variables* are the same as [#http-variables](#http-variables) but with TLS encryption for Streamable HTTP. HTTPS variables require an [#ssl-certificate](#ssl-certificate) however, redefining the keystore parameter default values is optional. | Environment variable | Description | Default | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | SONARQUBE\_TRANSPORT | Set to `https` to enable Streamable HTTP transport over TLS | not defined (stdio) | | SONARQUBE\_HTTP\_HOST | Host to bind. Use `127.0.0.1` for localhost. Use `0.0.0.0` for the container image. | 127.0.0.1 | | SONARQUBE\_HTTP\_PORT | Port number (typically 8443 for HTTPS), or `0` for an OS-assigned port | 8080 | | SONARQUBE\_HTTP\_ALLOWED\_ORIGINS | Comma-separated browser origins allowed for CORS (for example, `https://my-app.example.com`) | not defined | | SONARQUBE\_MCP\_IN\_CONTAINER | Set to `true` in custom container images to suppress the startup warning when binding to `0.0.0.0`. Already set in the official image. | false | If needed, information about HTTP and HTTPS [proxy settings](/sonarqube-mcp-server/setup/environment-considerations.md#proxy) is available on the [Environment considerations](/sonarqube-mcp-server/setup/environment-considerations.md) page. ### CORS policy In Streamable HTTP mode (`http` or `https`), the server validates the browser `Origin` header as a browser-layer backstop on local bindings. Bearer token authentication remains the primary access control. **Origin enforcement** (returns 403 when triggered): * Applies only on local bindings (`127.0.0.1`, `localhost`, `0.0.0.0`) * Skipped when the request carries `Authorization: Bearer …` or the legacy `SONARQUBE_TOKEN` header (native MCP clients such as Cursor and Claude Desktop) * Skipped on OAuth discovery paths without a token: `POST /mcp` (401 discovery) and `GET /.well-known/*` (Protected Resource Metadata) * Not applied on remote host bindings (for example, SonarQube Cloud hosted); use `SONARQUBE_HTTP_ALLOWED_ORIGINS` for browser CORS only **Allowed origins** (for CORS response headers and local enforcement): * When bound to `127.0.0.1` or `localhost` (default): localhost browser origins (`http://localhost`, `http://127.0.0.1`, `http://[::1]`, with any port) * When bound to `0.0.0.0` (required for container port mapping): same CORS policy as localhost bindings * Use `SONARQUBE_HTTP_ALLOWED_ORIGINS` to add full origin URLs to the allowlist (for example, `https://sonarcloud.io, https://my-app.example.com`) when deploying behind a web application ## SSL certificate | Environment variable | Description | Default | | ----------------------------------- | ------------------------------------------------------------------------------- | --------------------------- | | `SONARQUBE_HTTPS_KEYSTORE_PASSWORD` | Keystore password. Redefining the default value is optional. | `sonarlint` | | `SONARQUBE_HTTPS_KEYSTORE_PATH` | Path to keystore file (.p12 or .jks). Redefining the default value is optional. | `/etc/ssl/mcp/keystore.p12` | | `SONARQUBE_HTTPS_KEYSTORE_TYPE` | Keystore type (PKCS12 or JKS). Redefining the default value is optional. | `PKCS12` | See also the [Custom certificates](/sonarqube-mcp-server/setup/environment-considerations.md#custom-certificates) article for information about supported formats and using the container image with custom configurations of your certificate. ## SOCKS5 proxy 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` | ## Tool enablement MCP clients load every enabled tool (its name, description, and input schema) into your agent's context on every conversation. Limit that list with `SONARQUBE_TOOLSETS` to cut context usage and the token cost of each session. By default, only important toolsets are enabled. Enable additional toolsets only when you need them. ### SONARQUBE\_TOOLSETS Comma-separated list of toolsets to enable. When defined, only the listed toolsets are available. If not defined, the following toolsets are enabled by default: `analysis`, `ide`, `issues`, `projects`, `quality-gates`, `rules`, `duplications`, `measures`, `security-hotspots`, `dependency-risks`, `coverage`, `cag`, `agentic-readiness`. > **Note:** The `projects` toolset is always enabled because 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 subscription. The default toolsets include `cag` and `analysis`, which means a default stdio install loads the Vortex tools when your SonarQube Cloud organization or SonarQube Server has an active Vortex subscription, and the server then logs the deprecation warning described below. To avoid the warning, set `SONARQUBE_TOOLSETS` explicitly and include `vortex` along with every other toolset you need, because setting the variable replaces the defaults. Without a subscription, the Vortex tools do not load, and over Streamable HTTP they never load. On SonarQube Cloud, built-in `run_advanced_code_analysis` checks the organization selected for that call. Proxied context tools use the organization resolved at startup. Use the unified `vortex` toolset key. The deprecated `cag` and `analysis` keys still work on SonarQube Cloud and SonarQube Server 2026.5; 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 [Self-hosted setups](/sonarqube-mcp-server/setup/self-hosted.md) for details. Agentic Readiness tools are available only on SonarQube Cloud when the feature is enabled for your organization. In stdio mode, the server checks the feature flag at startup. In HTTP or HTTPS mode, the server does not load these tools unless you opt in explicitly. To opt in, set `SONARQUBE_TOOLSETS` on the server and include `agentic-readiness` along with every other toolset you need, because setting the variable replaces the defaults. ### SONARQUBE\_READ\_ONLY When set to `true`, enables read-only mode and disables all write operations (for example, changing issue status). This filter is cumulative with `SONARQUBE_TOOLSETS` if both are defined. 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 [Self-hosted setups](/sonarqube-mcp-server/setup/self-hosted.md) for details. ### Available toolsets | 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`. | | **Coverage** | `coverage` | Test coverage analysis and improvement tools | | **Dependency Risks** | `dependency-risks` | Analyze dependency risks and security issues (SCA) | | **Duplications** | `duplications` | Find code duplications across projects | | **Issues** | `issues` | Search and manage SonarQube issues | | **Languages** | `languages` | List supported programming languages | | **Measures** | `measures` | Retrieve metrics and measures (includes both measures and metrics tools) | | **Portfolios** | `portfolios` | Manage portfolios and enterprises (SonarQube Cloud and Server) | | **Projects** | `projects` | Browse and search SonarQube projects, and list SonarQube Cloud organizations | | **Quality Gates** | `quality-gates` | Access quality gates and their status | | **Rules** | `rules` | Browse and search SonarQube rules | | **Security Hotspots** | `security-hotspots` | Search and review security hotspots | | **Sources** | `sources` | Access source code and SCM information | | **System** | `system` | System administration tools (SonarQube Server only) | | **Webhooks** | `webhooks` | Manage webhooks | | **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); the connected SonarQube Cloud plan or SonarQube Server license must have an active subscription | | **Agentic Readiness** | `agentic-readiness` | Agentic Readiness Assessment tools (SonarQube Cloud; stdio requires the organization feature flag, HTTP or HTTPS requires explicit server opt-in) | | **Architecture** | `architecture` | Read current and intended architecture, and replace intended models (not enabled by default). SonarQube Cloud requires a Team or Enterprise plan. SonarQube Server registers current reads only. | **Toolset examples** > **Note:** Although the examples below use `docker`, any OCI-compatible container runtime works (for example, Podman, nerdctl, etc). Simply replace `docker` with commands specific to your preferred tool. > **Warning:** *User tokens* are required when setting up connected mode or your SonarQube MCP server with SonarQube (Server, Cloud). Your binding will not function properly if you use *project tokens*, *global tokens*, or *scoped organization tokens* during setup. > **Note:** Docker's MCP Hub publishes the [`mcp/sonarqube`](https://hub.docker.com/r/mcp/sonarqube) image on its own cadence, so it may occasionally lag behind the latest release. The examples below use [`sonarsource/sonarqube-mcp`](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags) instead, which receives new releases first and supports versioned tags for stable pinning. **Enable analysis, issues, and quality gates toolsets (using Docker with SonarQube Cloud):** ```bash docker run -i --init --pull=always --name sonarqube-mcp-server --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, and you do not need to include it in `SONARQUBE_TOOLSETS`. > **Note:** `SONARQUBE_URL` should be defined as `https://sonarqube.us` each time you connect to a SonarQube Cloud organization in the US region. Without it, the server connects to the EU region. See the [Connecting to SonarQube Cloud in the US region](/sonarqube-mcp-server/setup/environment-considerations.md#connecting-to-sonarqube-cloud-in-the-us-region) section for details. **Enable read-only mode (using Docker with SonarQube Cloud):** ```bash docker run -i --init --pull=always --name sonarqube-mcp-server --rm \ -e SONARQUBE_TOKEN="" \ -e SONARQUBE_ORG="" \ -e SONARQUBE_READ_ONLY="true" \ sonarsource/sonarqube-mcp ``` ## SonarQube Server-hosted MCP configuration The following properties configure the MCP proxy on SonarQube Server. Set them in `conf/sonar.properties`. | 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) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sonarsource.com/sonarqube-mcp-server/reference/environment-variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.