# Environment variables

Depending on which Sonar product you want the MCP Server to connect to and the server type you want to deploy, you will need to provide different environment variables. The variables are broken into found main categories, dependent on your environment's needs.

## Common variables

*Common variables* are required for all configuration typologies and must be defined before starting the server. To enable full functionality irregardless of your [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md#transport-mode), use these variables to initialize and authenticate your SonarQube MCP Server:

| Environment variable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SONARQUBE\_ORG       | <p>For SonarQube Cloud only.</p><p>Your SonarQube Cloud organization <a href="https://sonarcloud.io/account/organizations">key</a></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| SONARQUBE\_TOKEN     | <p>Your SonarQube Cloud token (see <a data-mention href="/spaces/B4UT2GNiZKjtxFtcFAL7/pages/7RNz5yJO6UMFBAycDUOq">/spaces/B4UT2GNiZKjtxFtcFAL7/pages/7RNz5yJO6UMFBAycDUOq</a>) or your SonarQube Server token (see <a data-mention href="/spaces/8MaL7qHHph0mwB0jcBjB/pages/zyNRpdLvMhY1TafVS14d">/spaces/8MaL7qHHph0mwB0jcBjB/pages/zyNRpdLvMhY1TafVS14d</a>).</p><p><strong>Deprecation notice (HTTP(S) transport):</strong> Passing the token via a <code>SONARQUBE\_TOKEN</code> HTTP header is deprecated. Use the <code>Authorization: Bearer \<YourSonarQubeUserToken></code> header instead. For stdio transport, <code>SONARQUBE\_TOKEN</code> as an environment variable is unchanged. See <a data-mention href="/pages/9nmUtqfmnJjznR23jK3B">/pages/9nmUtqfmnJjznR23jK3B</a> for details.</p> |
| SONARQUBE\_URL       | <ul><li>Required when connecting to SonarQube Server and SonarQube Community Build: define as your <a data-mention href="/spaces/8MaL7qHHph0mwB0jcBjB/pages/yDVaGZL7CAgkqGv98Bt6">/spaces/8MaL7qHHph0mwB0jcBjB/pages/yDVaGZL7CAgkqGv98Bt6</a>.</li><li>Required when connecting to SonarQube Cloud in the US region: define as <code><https://sonarqube.us></code>.</li><li>Not required to connect to SonarQube Cloud in the EU region: the default value is <code><https://sonarcloud.io></code>.</li></ul>                                                                                                                                                                                                                                                                                            |

{% hint style="warning" %}
*User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process.
{% endhint %}

## 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 are required, or not, depending on your configuration, or if for example, you are 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\_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. |
| 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.               |
| 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.                |

## HTTP variables

*HTTP variables* are used when multiple clients are connecting to a shared MCP server. Each client provides its own user token.

{% hint style="danger" %}
The HTTP [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md#transport-mode) is not recommended. Use [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md#stdio) for local development or [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md#https) for multi-user production deployments.
{% endhint %}

| Environment variable  | Description                                       | Default             |
| --------------------- | ------------------------------------------------- | ------------------- |
| SONARQUBE\_TRANSPORT  | Set to `http` to enable 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 for HTTP server: 1024-65535           | 8080                |

If needed, information about HTTP and HTTPS [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md#proxy) settings is available on the [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md) page.

## HTTPS variables

*HTTPS variables* are the same as [#http-variables](#http-variables "mention") but with TLS encryption. HTTPS variables require an [#ssl-certificate](#ssl-certificate "mention") however, redefining the keystore parameter default values is optional.

| Environment variable  | Description                                                                             | Default             |
| --------------------- | --------------------------------------------------------------------------------------- | ------------------- |
| SONARQUBE\_TRANSPORT  | Set to `https` to enable HTTPS transport                                                | not defined (stdio) |
| SONARQUBE\_HTTP\_HOST | Host to bind. Use `127.0.0.1` for localhost. Use `0.0.0.0` for for the container image. | 127.0.0.1           |
| SONARQUBE\_HTTP\_PORT | Typically port 8443 for HTTPS.                                                          | 8080                |

If needed, information about HTTP and HTTPS [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md#proxy) settings is available on the [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.md) page.

## SSL certificate

<table><thead><tr><th width="284.8203125">Environment variable</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>SONARQUBE_HTTPS_KEYSTORE_PASSWORD</td><td>Keystore password. Redefining the default value is optional.</td><td><code>sonarlint</code></td></tr><tr><td>SONARQUBE_HTTPS_KEYSTORE_PATH</td><td>Path to keystore file (.p12 or .jks). Redefining the default value is optional.</td><td><code>/etc/ssl/mcp/keystore.p12</code></td></tr><tr><td>SONARQUBE_HTTPS_KEYSTORE_TYPE</td><td>Keystore type (PKCS12 or JKS). Redefining the default value is optional.</td><td><code>PKCS12</code></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>

See also the [Configure your MCP server](/sonarqube-mcp-server/build-and-configure/configure.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

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

| Environment variable  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SONARQUBE\_TOOLSETS   | <p>Comma-separated list of toolsets to enable. When defined, only the listed toolsets will be available. If not defined, default important toolsets are enabled (<code>analysis</code>, <code>issues</code>, <code>projects</code>, <code>quality-gates</code>, <code>rules</code>, <code>duplications</code>, <code>measures</code>, <code>security-hotspots</code>, <code>dependency-risks</code>, <code>coverage</code>, <code>cag</code>).<br><strong>Note:</strong> The <code>projects</code> toolset is always enabled because it's required to find project keys for other operations.</p> |
| SONARQUBE\_READ\_ONLY | <p>When set to <code>true</code>, enables read-only mode which disables all write operations; for example, changing issue status. This filter is cumulative with <code>SONARQUBE\_TOOLSETS</code> if both are defined.<br>Default: <code>false</code>.</p>                                                                                                                                                                                                                                                                                                                                        |

<details>

<summary>Available toolsets</summary>

<table><thead><tr><th width="172.8515625">Toolset</th><th width="194.85546875">Key</th><th>Description</th></tr></thead><tbody><tr><td><strong>Analysis</strong></td><td><code>analysis</code></td><td>Code analysis tools (analyze code snippets and files)</td></tr><tr><td><strong>Context Augmentation</strong></td><td><code>cag</code></td><td>Context Augmentation tools for guiding AI agents with architectural awareness and coding guidelines</td></tr><tr><td><strong>Coverage</strong></td><td><code>coverage</code></td><td>Test coverage analysis and improvement tools</td></tr><tr><td><strong>Dependency Risks</strong></td><td><code>dependency-risks</code></td><td>Analyze dependency risks and security issues (SCA)</td></tr><tr><td><strong>Duplications</strong></td><td><code>duplications</code></td><td>Find code duplications across projects</td></tr><tr><td><strong>Issues</strong></td><td><code>issues</code></td><td>Search and manage SonarQube issues</td></tr><tr><td><strong>Languages</strong></td><td><code>languages</code></td><td>List supported programming languages</td></tr><tr><td><strong>Measures</strong></td><td><code>measures</code></td><td>Retrieve metrics and measures (includes both measures and metrics tools)</td></tr><tr><td><strong>Portfolios</strong></td><td><code>portfolios</code></td><td>Manage portfolios and enterprises (SonarQube Cloud and Server)</td></tr><tr><td><strong>Projects</strong></td><td><code>projects</code></td><td>Browse and search SonarQube projects</td></tr><tr><td><strong>Quality Gates</strong></td><td><code>quality-gates</code></td><td>Access quality gates and their status</td></tr><tr><td><strong>Rules</strong></td><td><code>rules</code></td><td>Browse and search SonarQube rules</td></tr><tr><td><strong>Security Hotspots</strong></td><td><code>security-hotspots</code></td><td>Search and review Security Hotspots</td></tr><tr><td><strong>Sources</strong></td><td><code>sources</code></td><td>Access source code and SCM information</td></tr><tr><td><strong>System</strong></td><td><code>system</code></td><td>System administration tools (SonarQube Server only)</td></tr><tr><td><strong>Webhooks</strong></td><td><code>webhooks</code></td><td>Manage webhooks</td></tr></tbody></table>

**Toolset examples**

{% hint style="info" %}
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.
{% endhint %}

{% hint style="success" %}
SONARQUBE\_URL should be defined as `https://sonarqube.us` each time you use a SonarQube Cloud configuration (SONARQUBE\_TOKEN + SONARQUBE\_ORG) and want to connect to US instance. See the [Environment variables](/sonarqube-mcp-server/build-and-configure/environment-variables.md#common-variables) article which explains when to use these variables.
{% endhint %}

**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="<YourSonarQubeUserToken>" \
  -e SONARQUBE_ORG="<YourOrganizationName>" \
  -e SONARQUBE_TOOLSETS="analysis,issues,quality-gates" \
  mcp/sonarqube
```

* 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):**

```bash
docker run -i --init --pull=always --name sonarqube-mcp-server --rm \
  -e SONARQUBE_TOKEN="<YourSonarQubeUserToken>" \
  -e SONARQUBE_ORG="<YourOrganizationName>" \
  -e SONARQUBE_READ_ONLY="true" \
  mcp/sonarqube

```

{% hint style="warning" %}
*User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process.
{% endhint %}

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/environment-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.