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; see each variable for details.
SONARQUBE_ORG
For SonarQube Cloud only. Optional organization key. When set, it fixes the Cloud organization.
In stdio mode, a token without 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, 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 and Deprecations and removals.
On the SonarQube Cloud-hosted MCP server, an OAuth request rejects a SONARQUBE_ORG header. Call list_organizations, 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) or your SonarQube Server token (see Managing your tokens).
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 <YourSonarQubeUserToken> header with every request. To enable analyze_code_snippet over HTTP or HTTPS, set a startup SONARQUBE_TOKEN. The analysis toolset is enabled by default; if you set SONARQUBE_TOOLSETS, include analysis. The startup token initializes the analyzers. On SonarQube Cloud, analyzer downloads are anonymous, and analysis calls use the caller's token and the organization selected for the request to retrieve quality profiles and active rules. Without a startup token, snippet analysis and analyzer downloads are unavailable, even with SONARQUBE_FORCE_LOCAL_ANALYSIS=true.
Deprecation notice (Streamable HTTP transport): For SonarQube tokens, passing the token via a
SONARQUBE_TOKENHTTP header is deprecated. Use theAuthorization: Bearer <YourSonarQubeUserToken>header instead. The SonarQube Cloud-hosted MCP server also accepts OAuth sign-in. For stdio transport,SONARQUBE_TOKENas an environment variable is unchanged. See HTTPS for details.
SONARQUBE_URL
SonarQube Server or SonarQube Community Build: Set to your Server base URL.
SonarQube Cloud, US region: Set to
https://sonarqube.us.SonarQube Cloud, EU region: Not required. The default is
https://sonarcloud.io. A token withoutSONARQUBE_URLconnects 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.
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:
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_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.
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 is available on the Environment considerations page.
HTTPS variables
HTTPS variables are the same as #http-variables but with TLS encryption for Streamable HTTP. HTTPS variables require an #ssl-certificate however, redefining the keystore parameter default values is optional.
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 is available on the Environment considerations 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 legacySONARQUBE_TOKENheader (native MCP clients such as Cursor and Claude Desktop)Skipped on OAuth discovery paths without a token:
POST /mcp(401 discovery) andGET /.well-known/*(Protected Resource Metadata)Not applied on remote host bindings (for example, SonarQube Cloud hosted); use
SONARQUBE_HTTP_ALLOWED_ORIGINSfor browser CORS only
Allowed origins (for CORS response headers and local enforcement):
When bound to
127.0.0.1orlocalhost(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 bindingsUse
SONARQUBE_HTTP_ALLOWED_ORIGINSto 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
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 article for information about supported formats and using the container image with custom configurations of your certificate.
SOCKS5 proxy
SOCKS5 proxies are supported.
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
projectstoolset 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 includecagandanalysis, 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, setSONARQUBE_TOOLSETSexplicitly and includevortexalong 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-inrun_advanced_code_analysischecks the organization selected for that call. Proxied context tools use the organization resolved at startup. Use the unifiedvortextoolset key. The deprecatedcagandanalysiskeys 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 withoutvortex. In Streamable HTTP mode, clients can send aSONARQUBE_TOOLSETSHTTP header to narrow this further per-request, but cannot enable toolsets beyond what the server was launched with. See Self-hosted setups 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 for details.
Available toolsets
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, project directives, and project findings; replace intended models; and create, update, or delete project directives (not enabled by default). SonarQube Cloud requires a Team or Enterprise plan. On SonarQube Server, these tools require version 2026.6 or later and Developer edition or higher; they are not available on older versions or SonarQube Community Build.
Toolset examples
Note: Although the examples below use
docker, any OCI-compatible container runtime works (for example, Podman, nerdctl, etc). Simply replacedockerwith 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/sonarqubeimage on its own cadence, so it may occasionally lag behind the latest release. The examples below usesonarsource/sonarqube-mcpinstead, which receives new releases first and supports versioned tags for stable pinning.
Enable analysis, issues, and quality gates toolsets (using Docker with SonarQube Cloud):
Note: The
projectstoolset is always enabled automatically, and you do not need to include it inSONARQUBE_TOOLSETS.
Note:
SONARQUBE_URLshould be defined ashttps://sonarqube.useach 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 section for details.
Enable read-only mode (using Docker with SonarQube Cloud):
SonarQube Server-hosted MCP configuration
The following properties configure the MCP proxy on SonarQube Server. Set them in conf/sonar.properties.
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)
Last updated
Was this helpful?

