# 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 [#transport-mode](https://docs.sonarsource.com/sonarqube-mcp-server/configure#transport-mode "mention"), use these variables to initialize and authenticate your SonarQube MCP Server:

| 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\_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\_ORG                     | <p>For SonarQube Cloud only.</p><p>Your SonarQube Cloud organization <a href="https://sonarcloud.io/account/organizations">key</a></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 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\_TOKEN                   | <p>Your SonarQube Cloud token (see <a data-mention href="https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/managing-your-account/managing-tokens">Managing Personal Access Tokens</a>) or your SonarQube Server token (see <a data-mention href="https://app.gitbook.com/s/8MaL7qHHph0mwB0jcBjB/user-guide/managing-tokens">Managing your tokens</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="../deprecations-and-removals">deprecations-and-removals</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="https://app.gitbook.com/s/8MaL7qHHph0mwB0jcBjB/instance-administration/server-base-url">Server base URL</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                                                                                                                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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\_IDE\_PORT | Optional port number between 64120 and 64130 used to connect SonarQube MCP Server with SonarQube for IDE.                                                                                                    |

## 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 [#transport-mode](https://docs.sonarsource.com/sonarqube-mcp-server/configure#transport-mode "mention") is not recommended. Use [#stdio](https://docs.sonarsource.com/sonarqube-mcp-server/configure#stdio "mention") for local development or [#https](https://docs.sonarsource.com/sonarqube-mcp-server/configure#https "mention") 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 [#proxy](https://docs.sonarsource.com/sonarqube-mcp-server/configure#proxy "mention") settings is available on the [configure](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure "mention") 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 [#proxy](https://docs.sonarsource.com/sonarqube-mcp-server/configure#proxy "mention") settings is available on the [configure](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure "mention") 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 [#custom-certificates](https://docs.sonarsource.com/sonarqube-mcp-server/configure#custom-certificates "mention") 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 [#common-variables](#common-variables "mention") 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>