Skip to content
Back to search

sonarqube-mcp-server

Official SonarQube MCP Server for code quality and security in AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/SonarSource/sonarqube-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/SonarSource/sonarqube-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sonarsource--sonarqube-mcp-server/badge.svg)](/listings/sonarsource--sonarqube-mcp-server)

HTML

<a href="/listings/sonarsource--sonarqube-mcp-server"><img src="/api/listings/sonarsource--sonarqube-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<details> <summary>Security best practices</summary>

> πŸ”’ **Important**: Your SonarQube token is a sensitive credential. Follow these security practices:

**When using CLI commands:** - **Avoid hardcoding tokens** in command-line arguments – they get saved in shell history - **Use environment variables** – set tokens in environment variables before running commands

**When using configuration files:** - **Never commit tokens** to version control - **Use environment variable substitution** in config files when possible

</details>

πŸš€ Generate your configuration

The fastest way to get started is the **[SonarQube MCP Server Configuration Generator](https://mcp.sonarqube.com/config-generator.html)** – an interactive tool that produces a ready-to-use configuration for your preferred AI agent client.

Manual setup

If you prefer to configure things yourself, the simplest method is to use our container image at [sonarsource/sonarqube-mcp](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags). Use `sonarsource/sonarqube-mcp` for automatic updates (with `--pull=always`), or pin to a version tag (e.g., `sonarsource/sonarqube-mcp:1.19.0.2785`) for reproducible deployments. Read below if you want to build it locally.

> **Note:** While the examples below use `docker`, any OCI-compatible container runtime works (e.g., Podman, nerdctl). Simply replace `docker` with your preferred tool.

<details> <summary>Antigravity</summary>

SonarQube MCP Server is available in the Antigravity MCP Store. Follow these instructions:

1. Open the **Agent Side Panel** 2. Click the three dots (**...**) at the top right and select **MCP Servers** 3. Search for `SonarQube` and select **Install** 4. Provide the required SonarQube User token. You can also provide your organization key for SonarQube Cloud or the SonarQube URL if connecting to SonarQube Server.

For **SonarQube Cloud US**, set the URL to `https://sonarqube.us`.

Alternatively, you can manually configure the server via `mcp_config.json`:

* To connect with SonarQube Cloud:

In the Agent Side Panel, click the three dots (**...**) -> **MCP Store** -> **Manage MCP Servers** -> **View raw config**, and add the following:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "<YOUR_TOKEN>",
        "SONARQUBE_ORG": "<YOUR_ORG>"
      }
    }
  }
}

For **SonarQube Cloud US**, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section and `"-e", "SONARQUBE_URL"` to the `args` array.

* To connect with SonarQube Server:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
        "SONARQUBE_URL": "<YOUR_SERVER_URL>"
      }
    }
  }
}

</details>

<details> <summary>Claude Code</summary>

* To connect with SonarQube Cloud:

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  --env SONARQUBE_ORG=$SONAR_ORG \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

For **SonarQube Cloud US**, add `--env SONARQUBE_URL=https://sonarqube.us` to the command.

* To connect with SonarQube Server:

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  --env SONARQUBE_URL=$SONAR_URL \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL sonarsource/sonarqube-mcp

</details>

<details> <summary>Codex CLI</summary>

Manually edit the configuration file at `~/.codex/config.toml` and add the following configuration:

* To connect with SonarQube Cloud:

[mcp_servers.sonarqube]
command = "docker"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 1,736 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="https://assets-eu-01.kc-usercontent.com/ef593040-b591-0198-9506-ed88b30bc023/a23fc7ba-23f0-489a-829d-ed88c0748521/Sonar_Logo_Dark%20Backgrounds.svg">
  4. <img src="https://assets-eu-01.kc-usercontent.com/ef593040-b591-0198-9506-ed88b30bc023/82c13eba-d95c-4bb8-8007-7ce77c14e043/Sonar_Logo_Light%20Backgrounds.svg" alt="Sonar logo" width="400">
  5. </picture>
  6. </p>
  7. [![Build](https://github.com/SonarSource/sonarqube-mcp-server/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/SonarSource/sonarqube-mcp-server/actions/workflows/build.yml)
  8. [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=SonarSource_sonarqube-mcp-server&metric=alert_status&token=364a508a1e77096460f8571d8e66b41c99c95bea)](https://sonarcloud.io/summary/new_code?id=SonarSource_sonarqube-mcp-server)
  9. <!-- sonar-marketing:start -->
  10. <!-- Marketing maintains this section. For wording changes, consult the relevant Product Marketing Manager (PMM). Repository CODEOWNERS review accuracy and merge changes. -->
  11. # SonarQube MCP Server
  12. The SonarQube MCP Server is a Model Context Protocol (MCP) server that enables seamless integration with SonarQube Server or Cloud for code quality and security.
  13. It also supports the analysis of code snippet directly within the agent context.
  14. Start with the [quick setup](#quick-setup), or learn more about the [SonarQube product family](https://www.sonarsource.com/products/sonarqube/).
  15. <!-- sonar-marketing:end -->
  16. ## Quick setup
  17. <details>
  18. <summary>Security best practices</summary>
  19. > πŸ”’ **Important**: Your SonarQube token is a sensitive credential. Follow these security practices:
  20. **When using CLI commands:**
  21. - **Avoid hardcoding tokens** in command-line arguments – they get saved in shell history
  22. - **Use environment variables** – set tokens in environment variables before running commands
  23. **When using configuration files:**
  24. - **Never commit tokens** to version control
  25. - **Use environment variable substitution** in config files when possible
  26. </details>
  27. ### πŸš€ Generate your configuration
  28. The fastest way to get started is the **[SonarQube MCP Server Configuration Generator](https://mcp.sonarqube.com/config-generator.html)** – an interactive tool that produces a ready-to-use configuration for your preferred AI agent client.
  29. ### Manual setup
  30. If you prefer to configure things yourself, the simplest method is to use our container image at [sonarsource/sonarqube-mcp](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags). Use `sonarsource/sonarqube-mcp` for automatic updates (with `--pull=always`), or pin to a version tag (e.g., `sonarsource/sonarqube-mcp:1.19.0.2785`) for reproducible deployments. Some releases are also tagged with the SonarQube Server version they are aligned with, in the form `<SQS major>.<SQS minor>.<patch>` (e.g., `sonarsource/sonarqube-mcp:2026.5.0`), where the patch number is incremented for each MCP release targeting that SonarQube Server version. Read below if you want to build it locally.
  31. > **Note:** While the examples below use `docker`, any OCI-compatible container runtime works (e.g., Podman, nerdctl). Simply replace `docker` with your preferred tool.
  32. <details>
  33. <summary>Antigravity</summary>
  34. SonarQube MCP Server is available in the Antigravity MCP Store. Follow these instructions:
  35. 1. Open the **Agent Side Panel**
  36. 2. Click the three dots (**...**) at the top right and select **MCP Servers**
  37. 3. Search for `SonarQube` and select **Install**
  38. 4. Provide the required SonarQube User token. You can also provide your organization key for SonarQube Cloud or the SonarQube URL if connecting to SonarQube Server.
  39. For **SonarQube Cloud US**, set the URL to `https://sonarqube.us`.
  40. Alternatively, you can manually configure the server via `mcp_config.json`:
  41. * To connect with SonarQube Cloud:
  42. In the Agent Side Panel, click the three dots (**...**) -> **MCP Store** -> **Manage MCP Servers** -> **View raw config**, and add the following:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "sonarqube": {
  47. "command": "docker",
  48. "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"],
  49. "env": {
  50. "SONARQUBE_TOKEN": "<YOUR_TOKEN>",
  51. "SONARQUBE_ORG": "<YOUR_ORG>"
  52. }
  53. }
  54. }
  55. }
  56. ```
  57. For **SonarQube Cloud US**, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section and `"-e", "SONARQUBE_URL"` to the `args` array.
  58. * To connect with SonarQube Server:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "sonarqube": {
  63. "command": "docker",
  64. "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"],
  65. "env": {
  66. "SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
  67. "SONARQUBE_URL": "<YOUR_SERVER_URL>"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. </details>
  74. <details>
  75. <summary>Claude Code</summary>
  76. * To connect with SonarQube Cloud:
  77. ```bash
  78. claude mcp add sonarqube \
  79. --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  80. --env SONARQUBE_ORG=$SONAR_ORG \
  81. -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp
  82. ```
  83. For **SonarQube Cloud US**, add `--env SONARQUBE_URL=https://sonarqube.us` to the command.
  84. * To connect with SonarQube Server:
  85. ```bash
  86. claude mcp add sonarqube \
  87. --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  88. --env SONARQUBE_URL=$SONAR_URL \
  89. -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL sonarsource/sonarqube-mcp
  90. ```
  91. </details>
  92. <details>
  93. <summary>Codex CLI</summary>
  94. Manually edit the configuration file at `~/.codex/config.toml` and add the following configuration:
  95. * To connect with SonarQube Cloud:
  96. ```toml
  97. [mcp_servers.sonarqube]
  98. command = "docker"
  99. args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"]
  100. env = { "SONARQUBE_TOKEN" = "<YOUR_USER_TOKEN>", "SONARQUBE_ORG" = "<YOUR_ORG>" }
  101. ```
  102. For **SonarQube Cloud US**, add `"SONARQUBE_URL" = "https://sonarqube.us"` to the `env` section and `"-e", "SONARQUBE_URL"` to the `args` array.
  103. * To connect with SonarQube Server:
  104. ```toml
  105. [mcp_servers.sonarqube]
  106. command = "docker"
  107. args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"]
  108. env = { "SONARQUBE_TOKEN" = "<YOUR_TOKEN>", "SONARQUBE_URL" = "<YOUR_SERVER_URL>" }
  109. ```
  110. </details>
  111. <details>
  112. <summary>Cursor</summary>
  113. * To connect with SonarQube Cloud:
  114. [![Install for SonarQube Cloud](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=sonarqube&config=eyJlbnYiOnsiU09OQVJRVUJFX1RPS0VOIjoiWU9VUl9UT0tFTiIsIlNPTkFSUVVCRV9PUkciOiJZT1VSX1NPTkFSUVVCRV9PUkcifSwiY29tbWFuZCI6ImRvY2tlciBydW4gLS1pbml0IC0tcHVsbD1hbHdheXMgLWkgLS1ybSAtZSBTT05BUlFVQkVfVE9LRU4gLWUgU09OQVJRVUJFX09SRyBzb25hcnNvdXJjZS9zb25hcnF1YmUtbWNwIn0%3D)
  115. For **SonarQube Cloud US**, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section in your MCP configuration after installation.
  116. * To connect with SonarQube Server:
  117. [![Install for SonarQube Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=sonarqube&config=eyJlbnYiOnsiU09OQVJRVUJFX1RPS0VOIjoiWU9VUl9VU0VSX1RPS0VOIiwiU09OQVJRVUJFX1VSTCI6IllPVVJfU09OQVJRVUJFX1VSTCJ9LCJjb21tYW5kIjoiZG9ja2VyIHJ1biAtLWluaXQgLS1wdWxsPWFsd2F5cyAtaSAtLXJtIC1lIFNPTkFSUVVCRV9UT0tFTiAtZSBTT05BUlFVQkVfVVJMIHNvbmFyc291cmNlL3NvbmFycXViZS1tY3AifQ%3D%3D)
  118. </details>
  119. <details>
  120. <summary>Gemini CLI</summary>
  121. > **Note:** The Gemini CLI extension has moved to the [sonarqube-agent-plugins](https://github.com/SonarSource/sonarqube-agent-plugins) repository. Please install it from there going forward.
  122. You can install our MCP server extension by using the following command:
  123. ```bash
  124. gemini extensions install https://github.com/SonarSource/sonarqube-agent-plugins
  125. ```
  126. You will need to set the required environment variables before starting Gemini:
  127. **Environment Variables Required:**
  128. * **For SonarQube Cloud:**
  129. - `SONARQUBE_TOKEN` - Your SonarQube Cloud token
  130. - `SONARQUBE_ORG` - Your organization key
  131. - `SONARQUBE_URL` - (Optional) Set to `https://sonarqube.us` for SonarQube Cloud US
  132. * **For SonarQube Server:**
  133. - `SONARQUBE_TOKEN` - Your SonarQube Server USER token
  134. - `SONARQUBE_URL` - Your SonarQube Server URL
  135. Once installed, the extension will be installed under `<home>/.gemini/extensions/sonarqube/gemini-extension.json`.
  136. </details>
  137. <details>
  138. <summary>GitHub Copilot CLI</summary>
  139. After starting Copilot CLI, run the following command to add the SonarQube MCP server:
  140. ```bash
  141. /mcp add
  142. ```
  143. You will have to provide different information about the MCP server, you can use tab to navigate between fields.
  144. * To connect with SonarQube Cloud:
  145. ```
  146. Server Name: sonarqube
  147. Server Type: Local (Press 1)
  148. Command: docker
  149. Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, sonarsource/sonarqube-mcp
  150. Environment Variables: SONARQUBE_TOKEN=<YOUR_TOKEN>,SONARQUBE_ORG=<YOUR_ORG>
  151. Tools: *
  152. ```
  153. For **SonarQube Cloud US**, add `-e, SONARQUBE_URL` to Arguments and `SONARQUBE_URL=https://sonarqube.us` to Environment Variables.
  154. * To connect with SonarQube Server:
  155. ```
  156. Server Name: sonarqube
  157. Server Type: Local (Press 1)
  158. Command: docker
  159. Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_URL, sonarsource/sonarqube-mcp
  160. Environment Variables: SONARQUBE_TOKEN=<YOUR_USER_TOKEN>,SONARQUBE_URL=<YOUR_SERVER_URL>
  161. Tools: *
  162. ```
  163. The configuration file is located at `~/.copilot/mcp-config.json`.
  164. </details>
  165. <details>
  166. <summary>GitHub Copilot coding agent</summary>
  167. GitHub Copilot coding agent can leverage the SonarQube MCP server directly in your CI/CD.
  168. To add the secrets to your Copilot environment, follow the Copilot [documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#setting-up-a-copilot-environment-for-copilot-coding-agent). Only secrets with names prefixed with **COPILOT_MCP_** will be available to your MCP configuration.
  169. In your GitHub repository, navigate under **Settings -> Copilot -> Coding agent**, and add the following configuration in the MCP configuration section:
  170. * To connect with SonarQube Cloud:
  171. ```
  172. {
  173. "mcpServers": {
  174. "sonarqube": {
  175. "type": "local",
  176. "command": "docker",
  177. "args": [
  178. "run",
  179. "--init",
  180. "--pull=always",
  181. "--rm",
  182. "-i",
  183. "-e",
  184. "SONARQUBE_TOKEN",
  185. "-e",
  186. "SONARQUBE_ORG",
  187. "sonarsource/sonarqube-mcp"
  188. ],
  189. "env": {
  190. "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_TOKEN",
  191. "SONARQUBE_ORG": "COPILOT_MCP_SONARQUBE_ORG"
  192. },
  193. "tools": ["*"]
  194. }
  195. }
  196. }
  197. ```
  198. For **SonarQube Cloud US**, add `"-e", "SONARQUBE_URL"` to the `args` array and `"SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL"` to the `env` section, then set the secret `COPILOT_MCP_SONARQUBE_URL=https://sonarqube.us`.
  199. * To connect with SonarQube Server:
  200. ```
  201. {
  202. "mcpServers": {
  203. "sonarqube": {
  204. "type": "local",
  205. "command": "docker",
  206. "args": [
  207. "run",
  208. "--init",
  209. "--pull=always",
  210. "--rm",
  211. "-i",
  212. "-e",
  213. "SONARQUBE_TOKEN",
  214. "-e",
  215. "SONARQUBE_URL",
  216. "sonarsource/sonarqube-mcp"
  217. ],
  218. "env": {
  219. "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_USER_TOKEN",
  220. "SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL"
  221. },
  222. "tools": ["*"]
  223. }
  224. }
  225. }
  226. ```
  227. </details>
  228. <details>
  229. <summary>Kiro</summary>
  230. Create a `.kiro/settings/mcp.json` file in your workspace directory (or edit if it already exists), add the following configuration:
  231. * To connect with SonarQube Cloud:
  232. ```
  233. {
  234. "mcpServers": {
  235. "sonarqube": {
  236. "command": "docker",
  237. "args": [
  238. "run",
  239. "--init",
  240. "--pull=always",
  241. "-i",
  242. "--rm",
  243. "-e",
  244. "SONARQUBE_TOKEN",
  245. "-e",
  246. "SONARQUBE_ORG",
  247. "sonarsource/sonarqube-mcp"
  248. ],
  249. "env": {
  250. "SONARQUBE_TOKEN": "<YOUR_TOKEN>",
  251. "SONARQUBE_ORG": "<YOUR_ORG>"
  252. },
  253. "disabled": false,
  254. "autoApprove": []
  255. }
  256. }
  257. }
  258. ```
  259. For **SonarQube Cloud US**, add `"-e", "SONARQUBE_URL"` to the `args` array and `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section.
  260. * To connect with SonarQube Server:
  261. ```
  262. {
  263. "mcpServers": {
  264. "sonarqube": {
  265. "command": "docker",
  266. "args": [
  267. "run",
  268. "--init",
  269. "--pull=always",
  270. "-i",
  271. "--rm",
  272. "-e",
  273. "SONARQUBE_TOKEN",
  274. "-e",
  275. "SONARQUBE_URL",
  276. "sonarsource/sonarqube-mcp"
  277. ],
  278. "env": {
  279. "SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
  280. "SONARQUBE_URL": "<YOUR_SERVER_URL>"
  281. },
  282. "disabled": false,
  283. "autoApprove": []
  284. }
  285. }
  286. }
  287. ```
  288. </details>
  289. <details>
  290. <summary>VS Code</summary>
  291. You can use the following buttons to simplify the installation process within VS Code.
  292. [![Install for SonarQube Cloud](https://img.shields.io/badge/VS_Code-Install_for_SonarQube_Cloud-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=sonarqube&inputs=%5B%7B%22id%22%3A%22SONARQUBE_TOKEN%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22SonarQube%20Cloud%20Token%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22SONARQUBE_ORG%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22SonarQube%20Cloud%20Organization%20Key%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--init%22%2C%22--pull%3Dalways%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22SONARQUBE_TOKEN%22%2C%22-e%22%2C%22SONARQUBE_ORG%22%2C%22mcp%2Fsonarqube%22%5D%2C%22env%22%3A%7B%22SONARQUBE_TOKEN%22%3A%22%24%7Binput%3ASONARQUBE_TOKEN%7D%22%2C%22SONARQUBE_ORG%22%3A%22%24%7Binput%3ASONARQUBE_ORG%7D%22%7D%7D)
  293. For **SonarQube Cloud US**, manually add `"SONARQUBE_URL": "https://sonarqube.us"` to the `env` section in your MCP configuration after installation.
  294. [![Install for SonarQube Server](https://img.shields.io/badge/VS_Code-Install_for_SonarQube_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=sonarqube&inputs=%5B%7B%22id%22%3A%22SONARQUBE_TOKEN%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22SonarQube%20Server%20User%20Token%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22SONARQUBE_URL%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22SonarQube%20Server%20URL%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--init%22%2C%22--pull%3Dalways%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22SONARQUBE_TOKEN%22%2C%22-e%22%2C%22SONARQUBE_URL%22%2C%22mcp%2Fsonarqube%22%5D%2C%22env%22%3A%7B%22SONARQUBE_TOKEN%22%3A%22%24%7Binput%3ASONARQUBE_TOKEN%7D%22%2C%22SONARQUBE_URL%22%3A%22%24%7Binput%3ASONARQUBE_URL%7D%22%7D%7D)
  295. </details>
  296. <details>
  297. <summary>Windsurf</summary>
  298. SonarQube MCP Server is available as a Windsurf plugin. Follow these instructions:
  299. 1. Open Windsurf **Settings** > **Cascade** > **MCP Servers** and select **Open MCP Marketplace**
  300. 2. Search for `sonarqube` on the Cascade MCP Marketplace
  301. 3. Choose the **SonarQube MCP Server** and select **Install**
  302. 4. Add the required SonarQube User token. Optionally add a default organization key for SonarQube Cloud, or add the SonarQube URL for SonarQube Server or Community Build.
  303. For **SonarQube Cloud US**, set the URL to `https://sonarqube.us`.
  304. </details>
  305. <details>
  306. <summary>Zed</summary>
  307. Navigate to the **Extensions** view in Zed and search for **SonarQube MCP Server**.
  308. When installing the extension, you will be prompted to provide the necessary environment variables:
  309. * When using SonarQube Cloud:
  310. ```
  311. {
  312. "sonarqube_token": "YOUR_SONARQUBE_TOKEN",
  313. "sonarqube_org": "SONARQUBE_ORGANIZATION_KEY",
  314. "docker_path": "DOCKER_PATH"
  315. }
  316. ```
  317. For **SonarQube Cloud US**, add `"sonarqube_url": "https://sonarqube.us"` to the configuration.
  318. * When using SonarQube Server:
  319. ```
  320. {
  321. "sonarqube_token": "YOUR_SONARQUBE_USER_TOKEN",
  322. "sonarqube_url": "YOUR_SONARQUBE_SERVER_URL",
  323. "docker_path": "DOCKER_PATH"
  324. }
  325. ```
  326. The `docker_path` is the path to a docker executable. Examples:
  327. Linux/macOS: `/usr/bin/docker` or `/usr/local/bin/docker`
  328. Windows: `C:\Program Files\Docker\Docker\resources\bin\docker.exe`
  329. </details>
  330. > πŸ’‘ **Tip:** We recommend pulling the latest image regularly or before reporting issues to ensure you have the most up-to-date features and fixes.
  331. ## Manual installation
  332. You can manually install the SonarQube MCP server by copying the following snippet in the MCP servers configuration file:
  333. * To connect with SonarQube Cloud:
  334. ```JSON
  335. {
  336. "sonarqube": {
  337. "command": "docker",
  338. "args": [
  339. "run",
  340. "--init",
  341. "--pull=always",
  342. "-i",
  343. "--rm",
  344. "-e",
  345. "SONARQUBE_TOKEN",
  346. "-e",
  347. "SONARQUBE_ORG",
  348. "sonarsource/sonarqube-mcp"
  349. ],
  350. "env": {
  351. "SONARQUBE_TOKEN": "<token>",
  352. "SONARQUBE_ORG": "<org>"
  353. }
  354. }
  355. }
  356. ```
  357. * To connect with SonarQube Server:
  358. ```JSON
  359. {
  360. "sonarqube": {
  361. "command": "docker",
  362. "args": [
  363. "run",
  364. "--init",
  365. "--pull=always",
  366. "-i",
  367. "--rm",
  368. "-e",
  369. "SONARQUBE_TOKEN",
  370. "-e",
  371. "SONARQUBE_URL",
  372. "sonarsource/sonarqube-mcp"
  373. ],
  374. "env": {
  375. "SONARQUBE_TOKEN": "<token>",
  376. "SONARQUBE_URL": "<url>"
  377. }
  378. }
  379. }
  380. ```
  381. ## Integration with SonarQube for IDE
  382. The SonarQube MCP Server can integrate with [SonarQube for IDE](https://www.sonarsource.com/products/sonarlint/) to further enhance your development workflow, providing better code analysis and insights directly within your IDE.
  383. <details>
  384. <summary>Configuration</summary>
  385. When using SonarQube for IDE, the `SONARQUBE_IDE_PORT` environment variable should be set with the correct port number. SonarQube for VS Code includes a Quick Install button, which automatically sets the correct port configuration.
  386. For example, with SonarQube Cloud:
  387. ```JSON
  388. {
  389. "sonarqube": {
  390. "command": "docker",
  391. "args": [
  392. "run",
  393. "--init",
  394. "--pull=always",
  395. "-i",
  396. "--rm",
  397. "-e",
  398. "SONARQUBE_TOKEN",
  399. "-e",
  400. "SONARQUBE_ORG",
  401. "-e",
  402. "SONARQUBE_IDE_PORT",
  403. "sonarsource/sonarqube-mcp"
  404. ],
  405. "env": {
  406. "SONARQUBE_TOKEN": "<token>",
  407. "SONARQUBE_ORG": "<org>",
  408. "SONARQUBE_IDE_PORT": "<64120-64130>"
  409. }
  410. }
  411. }
  412. ```
  413. > When running the MCP server in a container on Linux, the container cannot access the SonarQube for IDE embedded server running on localhost. To allow the container to connect to the SonarQube for IDE server, add the `--network=host` option to your container run command.
  414. </details>
  415. ## Configuration
  416. Depending on your environment, you should provide specific environment variables.
  417. ### Base
  418. You should add the following variable when running the MCP Server:
  419. | Environment variable | Description |
  420. |----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
  421. | `STORAGE_PATH` | Mandatory absolute path to a writable directory where SonarQube MCP Server will store its files (e.g., for creation, updates, and persistence), it is automatically provided when using the container image |
  422. | `SONARQUBE_PROJECT_KEY` | Optional default project key. When set, all tools that require a project key will use this value automatically β€” the `projectKey` parameter is removed from their schema entirely. Useful when working on a single project. |
  423. | `SONARQUBE_IDE_PORT` | Optional port number between 64120 and 64130 used to connect SonarQube MCP Server with SonarQube for IDE. |
  424. | `SONARQUBE_FORCE_LOCAL_ANALYSIS` | Set to `true` to use `analyze_code_snippet` instead of Vortex analysis on Cloud stdio, including for entitled organizations. Requires the `analysis` toolset. Default: `false`. Has no effect on SonarQube Server or Cloud HTTP. |
  425. | `SONARQUBE_DEBUG_ENABLED` | When set to `true`, enables debug logging. Debug logs are written to both the log file and STDERR. Useful for troubleshooting connectivity or configuration issues. Default: `false`. |
  426. | `SONARQUBE_LOG_TO_FILE_DISABLED` | When set to `true`, disables writing logs to disk entirely. No log files will be created under `STORAGE_PATH/logs/`. Useful in containerized or ephemeral environments where file logging is undesirable. Default: `false`. |
  427. ### Workspace Mount (Reducing Context Bloat)
  428. By default, analysis tool `analyze_code_snippet` requires the agent to pass the full file content as a `fileContent` argument. For large files or when analyzing many files in a session, this significantly increases context window usage and cost.
  429. **Solution:** mount your project directory into the container at `/app/mcp-workspace`. When this mount is detected, the server reads files directly from disk using the project-relative `filePath` argument β€” file content never passes through the agent context.
  430. ```json
  431. {
  432. "args": [
  433. "run", "-i", "--rm", "--init", "--pull=always",
  434. "-e", "SONARQUBE_TOKEN",
  435. "-e", "SONARQUBE_ORG",
  436. "-v", "/path/to/your/project:/app/mcp-workspace",
  437. "sonarsource/sonarqube-mcp"
  438. ]
  439. }
  440. ```
  441. With a mount, analysis tools read files directly using `filePath`; `fileContent` is not needed.
  442. Over stdio, analysis is selected at startup (subject to enabled toolsets):
  443. - **SonarQube Cloud:** Vortex analysis (`run_advanced_code_analysis`) with a workspace mount and at least one entitled organization; local analysis otherwise. Vortex analysis only accepts entitled organizations.
  444. - **SonarQube Server:** Vortex analysis for entitled instances (requires a workspace mount); local analysis for instances without Vortex.
  445. Local analysis uses SonarQube for IDE if connected or `analyze_code_snippet`. Without a mount, snippet analysis requires `fileContent`.
  446. On Cloud stdio, `SONARQUBE_ORG` limits the entitlement check to that organization. To use snippets for all organizations, set `SONARQUBE_FORCE_LOCAL_ANALYSIS=true`, enable the `analysis` toolset, and restart. This setting only affects Cloud stdio.
  447. Over HTTP/HTTPS, Cloud and Server support `analyze_code_snippet` when the MCP server has a startup `SONARQUBE_TOKEN` and the `analysis` toolset is enabled. The startup token is required for analyzer initialization (Cloud plugin downloads are anonymous); calls use the caller’s token and, on Cloud, the organization selected for the request to retrieve quality profiles and active rules. Without a startup token, snippet analysis and analyzer downloads are disabled, even with `SONARQUBE_FORCE_LOCAL_ANALYSIS=true`. Vortex entitlement is not required.
  448. ### Selective Tool Enablement
  449. MCP clients load every enabled tool β€” its name, description, and input schema β€” into the agent's context on every conversation. Limiting that list with `SONARQUBE_TOOLSETS` cuts context usage and the token cost of each session.
  450. By default, only important toolsets are enabled. Enable additional toolsets only when you need them.
  451. Agentic readiness is also selected by default on stdio when the organization is entitled. On HTTP it requires explicit `agentic-readiness` opt-in through `SONARQUBE_TOOLSETS`. Selecting a toolset does not bypass its transport, version, or entitlement requirements.
  452. | Environment variable | Description |
  453. |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
  454. | `SONARQUBE_TOOLSETS` | Comma-separated list of toolsets to enable. When set, only these toolsets will be available. If not set, default important toolsets are enabled (`analysis`, `ide`, `issues`, `projects`, `quality-gates`, `rules`, `duplications`, `measures`, `security-hotspots`, `dependency-risks`, `coverage`, `cag`). **Note:** The `projects` toolset is always enabled as 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 organization entitlement β€” an org must be entitled to both to use either. Cloud built-in analysis checks the organization selected at runtime; proxied context tools use the startup organization. On SonarQube Server, stdio lists Vortex context and `run_advanced_code_analysis` when both the CAG and A3S hubs are entitled. Prefer the unified `vortex` toolset key. The deprecated `cag` and `analysis` keys still work; 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 [Streamable HTTP transport](#2-http-streamable-http) below). |
  455. | `SONARQUBE_READ_ONLY` | When set to `true`, enables read-only mode which disables all write operations (changing issue status for example). This filter is cumulative with `SONARQUBE_TOOLSETS` if both are set. 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 [Streamable HTTP transport](#2-http-streamable-http) below). |
  456. <details>
  457. <summary>Available Toolsets</summary>
  458. | Toolset | Key | Description |
  459. |-----------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
  460. | **Analysis** | `analysis` | Code analysis tools (local analysis via `analyze_code_snippet`, **deprecated** in favor of `analyze_file_list`/Vortex analysis) |
  461. | **IDE** | `ide` | SonarQube for IDE bridge tools (file analysis, automatic analysis toggle) β€” currently also included in `analysis` |
  462. | **Issues** | `issues` | Search and manage SonarQube issues |
  463. | **Security Hotspots** | `security-hotspots` | Search and review Security Hotspots |
  464. | **Projects** | `projects` | Browse and search SonarQube projects |
  465. | **Quality Gates** | `quality-gates` | Access quality gates and their status |
  466. | **Rules** | `rules` | Browse and search SonarQube rules |
  467. | **Sources** | `sources` | Access source code and SCM information |
  468. | **Duplications** | `duplications` | Find code duplications across projects |
  469. | **Measures** | `measures` | Retrieve metrics and measures (includes both measures and metrics tools) |
  470. | **Languages** | `languages` | List supported programming languages |
  471. | **Portfolios** | `portfolios` | Manage portfolios and enterprises (Cloud and Server) |
  472. | **System** | `system` | System administration tools (Server only) |
  473. | **Webhooks** | `webhooks` | Manage webhooks |
  474. | **Dependency Risks** | `dependency-risks` | Analyze dependency risks and security issues (SCA) |
  475. | **Coverage** | `coverage` | Test coverage analysis and improvement tools |
  476. | **Vortex Context** | `cag` | Vortex context tools β€” stdio only. **Deprecated** in favor of `vortex` (old name: Context Augmentation/CAG) |
  477. | **Vortex** | `vortex` | Unified, **recommended** toolset surfacing both Vortex context and Vortex analysis tools under one name (stdio only; Cloud needs combined org entitlement; Server needs both hubs entitled) |
  478. | **Agentic Readiness** | `agentic-readiness` | Agentic Readiness Assessment tools (SonarQube Cloud, requires org entitlement) |
  479. | **Architecture** | `architecture` | Read architecture, replace intended models and manage project directives (not enabled by default) |
  480. #### Examples
  481. **Enable analysis, issues, and quality gates toolsets (using Docker with SonarQube Cloud):**
  482. ```bash
  483. docker run --init --pull=always -i --rm \
  484. -e SONARQUBE_TOKEN="<token>" \
  485. -e SONARQUBE_ORG="<org>" \
  486. -e SONARQUBE_TOOLSETS="analysis,issues,quality-gates" \
  487. sonarsource/sonarqube-mcp
  488. ```
  489. Note: The `projects` toolset is always enabled automatically, so you don't need to include it in `SONARQUBE_TOOLSETS`.
  490. **Enable read-only mode (using Docker with SonarQube Cloud):**
  491. ```bash
  492. docker run --init --pull=always -i --rm \
  493. -e SONARQUBE_TOKEN="<token>" \
  494. -e SONARQUBE_ORG="<org>" \
  495. -e SONARQUBE_READ_ONLY="true" \
  496. sonarsource/sonarqube-mcp
  497. ```
  498. </details>
  499. #### SonarQube Cloud
  500. For stdio, configure the following environment variables:
  501. | Environment variable | Description | Required |
  502. | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- |
  503. | `SONARQUBE_TOKEN` | Your SonarQube Cloud [token](https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens/) | Yes |
  504. | `SONARQUBE_ORG` | Optional fixed SonarQube Cloud organization [key](https://sonarcloud.io/account/organizations) | No |
  505. | `SONARQUBE_URL` | Custom SonarQube Cloud URL (defaults to `https://sonarcloud.io`). Use this for SonarQube Cloud US: `https://sonarqube.us` | No |
  506. **Examples:**
  507. - **SonarQube Cloud**: Only `SONARQUBE_TOKEN` is required. `SONARQUBE_ORG` fixes the organization when set.
  508. - **SonarQube Cloud US**: Set `SONARQUBE_TOKEN` and `SONARQUBE_URL=https://sonarqube.us`; `SONARQUBE_ORG` is optional.
  509. #### SonarQube Server
  510. | Environment variable | Description | Required |
  511. |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------|
  512. | `SONARQUBE_TOKEN` | Your SonarQube Server **USER** [token](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/managing-tokens/#generating-a-token) | Yes |
  513. | `SONARQUBE_URL` | Your SonarQube Server URL | Yes |
  514. > **Version requirement:** SonarQube Server **2025.1** (SQS) or **25.1** (SonarQube Community Build) or later is required. At startup, the MCP server reads the connected instance version and exits with an error if it is too old (for example, legacy 9.x/10.x Server releases and Community Build 24.x are not supported). SonarQube Cloud is not subject to this check.
  515. > ⚠️ Connection to SonarQube Server requires a token of type **USER** and will not function properly if project tokens or global tokens are used.
  516. > πŸ’‘ **Configuration Tip (stdio mode)**: A token without a URL defaults to SonarQube Cloud. Set `SONARQUBE_URL` for SonarQube Server or a different Cloud region. `SONARQUBE_ORG` fixes the Cloud organization when set.
  517. In stdio, setting `SONARQUBE_ORG` fixes the Cloud organization. Tool `organization` arguments are omitted from schemas and rejected, like `projectKey` when `SONARQUBE_PROJECT_KEY` is set.
  518. With `SONARQUBE_ORG` unset, agents can call `list_organizations` to discover organization keys, names, IDs, and UUIDs accessible to your user account, then pass a key as the optional `organization` argument on organization-aware tools. Stdio retains a uniquely detected organization as its default; zero or multiple organizations leave it unresolved. A tool argument applies only to that call and never changes the detected default. Snippet profile and rule lookups use the organization selected for that call.
  519. For HTTP/HTTPS token requests, server-level `SONARQUBE_ORG` remains supported for compatibility but is deprecated and logs a startup warning. It fixes the organization for every request and rejects client organization headers and tool `organization` arguments. When no server organization is configured, an optional client `SONARQUBE_ORG` header fixes the organization for that request and disallows tool `organization` arguments. Without the header, use the tool argument. Tools that require an organization report discovery guidance when all are missing. Organization discovery and tools whose APIs consume only resource identifiers do not require an organization argument. Organization-aware issue search and dependency-risk entitlement checks use the selected organization. When OAuth is configured, server-level `SONARQUBE_ORG` is rejected. OAuth requests also reject organization headers; select organizations through tool arguments.
  520. Vortex context tools use the configured or uniquely detected startup organization. Runtime organization arguments do not reconfigure the proxied context engine; unresolved startup organizations skip that proxy. The built-in `run_advanced_code_analysis` tool checks combined Vortex entitlement for the organization selected on each invocation.
  521. ### Transport Modes
  522. The [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) defines two transport mechanisms: **Stdio** and **Streamable HTTP**. The SonarQube MCP Server supports both:
  523. | MCP transport | Server mode | Typical use |
  524. |---------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------|
  525. | **Stdio** | Default (no `SONARQUBE_TRANSPORT`) | Local MCP clients that launch the server as a subprocess (Cursor, Claude Code, VS Code, etc.) |
  526. | **Streamable HTTP** | `SONARQUBE_TRANSPORT=http` or `https` | Remote or multi-user deployments; clients connect to `/mcp` over HTTP(S) (e.g. Windsurf with a self-hosted server URL) |
  527. > **Note:** **Streamable HTTP** is the current MCP network transport. The older SSE-only HTTP transport from earlier MCP versions is deprecated and not supported.
  528. #### 1. **Stdio** (Default - Recommended for Local Development)
  529. The recommended mode for local development and single-user setups, used by most MCP clients.
  530. **Example - Docker with SonarQube Cloud:**
  531. ```json
  532. {
  533. "mcpServers": {
  534. "sonarqube": {
  535. "command": "docker",
  536. "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"],
  537. "env": {
  538. "SONARQUBE_TOKEN": "<your-token>",
  539. "SONARQUBE_ORG": "<your-org>"
  540. }
  541. }
  542. }
  543. }
  544. ```
  545. #### 2. **HTTP (Streamable HTTP)**
  546. Unencrypted Streamable HTTP transport. Use HTTPS instead for multi-user deployments.
  547. > ⚠️ **Not Recommended:** Use **Stdio** for local development or **HTTPS (Streamable HTTP)** for multi-user production deployments.
  548. | Environment variable | Description | Default |
  549. |----------------------|------------------------------------------------------------------|-----------------|
  550. | `SONARQUBE_TRANSPORT`| Set to `http` to enable Streamable HTTP transport | Not set (stdio) |
  551. | `SONARQUBE_HTTP_PORT`| Port number (1024-65535), or `0` for an OS-assigned port | `8080` |
  552. | `SONARQUBE_HTTP_HOST`| Host to bind (defaults to localhost for security) | `127.0.0.1` |
  553. | `SONARQUBE_HTTP_ALLOWED_ORIGINS` | Comma-separated browser origins allowed for CORS (e.g. `https://my-app.example.com`) | Not set |
  554. | `SONARQUBE_MCP_IN_CONTAINER` | Set to `true` when running inside a container. The official Docker image sets this automatically; set it yourself when using other OCI runtimes (Podman, Kubernetes, Nomad, etc.). | `false` |
  555. **Note:** HTTP/HTTPS accepts the user's SonarQube token through `Authorization: Bearer <token>`. Sonar's hosted Cloud service also supports [OAuth](#hosted-sonarqube-cloud-oauth). For SonarQube Cloud token requests, the organization is resolved as follows:
  556. - `SONARQUBE_ORG` is an optional request header that fixes the organization for that request. Deprecated server-level configuration fixes it for all requests and rejects client organization headers and tool organization arguments.
  557. - Organization-aware tools accept an optional `organization` argument when neither server configuration nor the request header fixes the organization. Supplying the argument when the organization is fixed is rejected.
  558. - Without a default, agents can call `list_organizations` using only their token, then pass the chosen key to subsequent tools.
  559. Clients can also narrow the visible tools per-request by supplying `SONARQUBE_TOOLSETS` and/or `SONARQUBE_READ_ONLY` headers; these apply additional filtering on top of the server-level configuration β€” they can only reduce the scope, never expand it.
  560. No session state is maintained between requests.
  561. > **Deprecated:** For SonarQube tokens, the `SONARQUBE_TOKEN` request header is still accepted for backward compatibility but will be removed in a future version. Migrate to `Authorization: Bearer <token>`.
  562. #### 3. **HTTPS (Streamable HTTP over TLS)** (Recommended for Multi-User Production Deployments)
  563. Secure Streamable HTTP transport with TLS encryption. Requires SSL certificates.
  564. > βœ… **Recommended for Production:** Use HTTPS when deploying the MCP server for multiple users over Streamable HTTP. The server binds to `127.0.0.1` (localhost) by default for security.
  565. | Environment variable | Description | Default |
  566. |----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
  567. | `SONARQUBE_TRANSPORT` | Set to `https` to enable Streamable HTTP transport over TLS | Not set (stdio) |
  568. | `SONARQUBE_HTTP_PORT` | Port number (typically 8443 for HTTPS), or `0` for an OS-assigned port | `8080` |
  569. | `SONARQUBE_HTTP_HOST` | Host to bind (defaults to localhost for security) | `127.0.0.1` |
  570. | `SONARQUBE_HTTP_ALLOWED_ORIGINS` | Comma-separated browser origins allowed for CORS (e.g. `https://my-app.example.com`) | Not set |
  571. | `SONARQUBE_MCP_IN_CONTAINER` | Set to `true` when running inside a container. The official Docker image sets this automatically; set it yourself when using other OCI runtimes (Podman, Kubernetes, Nomad, etc.). | `false` |
  572. **SSL Certificate Configuration (Optional):**
  573. | Environment variable | Description | Default |
  574. |----------------------|------------------------------------------------|-----------------------------|
  575. | `SONARQUBE_HTTPS_KEYSTORE_PATH` | Path to keystore file (.p12 or .jks) | `/etc/ssl/mcp/keystore.p12` |
  576. | `SONARQUBE_HTTPS_KEYSTORE_PASSWORD`| Keystore password | `sonarlint` |
  577. | `SONARQUBE_HTTPS_KEYSTORE_TYPE` | Keystore type (PKCS12 or JKS) | `PKCS12` |
  578. **Example - Docker with SonarQube Cloud:**
  579. > **Note:** When running in a container, set `SONARQUBE_HTTP_HOST=0.0.0.0` so the container listens on all interfaces and the runtime's port mapping works, and set `SONARQUBE_MCP_IN_CONTAINER=true` to tell the server it is inside a container. The official Docker image sets the latter automatically; set it yourself when using other OCI runtimes (Podman, Kubernetes, Nomad, etc.). The host-side port flag controls who can reach the server from outside the container. `SONARQUBE_HTTP_HOST=0.0.0.0` only controls where the server listens inside the container β€” browser CORS still allows localhost origins by default.
  580. For a server running **locally on your machine** (accessible only from localhost):
  581. ```bash
  582. docker run --init --pull=always -p 127.0.0.1:8443:8443 \
  583. -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  584. -e SONARQUBE_TRANSPORT=https \
  585. -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  586. -e SONARQUBE_HTTP_PORT=8443 \
  587. sonarsource/sonarqube-mcp
  588. ```
  589. For a server **accessible from the network** (remote deployments):
  590. ```bash
  591. docker run --init --pull=always -p 8443:8443 \
  592. -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  593. -e SONARQUBE_TRANSPORT=https \
  594. -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  595. -e SONARQUBE_HTTP_PORT=8443 \
  596. sonarsource/sonarqube-mcp
  597. ```
  598. **Client Configuration (SonarQube Cloud):**
  599. For SonarQube token requests, optionally set `SONARQUBE_ORG` in client headers to fix the request organization, or omit it to select organizations through tool arguments.
  600. ```json
  601. {
  602. "mcpServers": {
  603. "sonarqube-https": {
  604. "url": "https://your-server:8443/mcp",
  605. "headers": {
  606. "Authorization": "Bearer <your-token>",
  607. "SONARQUBE_TOOLSETS": "issues,quality-gates",
  608. "SONARQUBE_READ_ONLY": "true"
  609. }
  610. }
  611. }
  612. }
  613. ```
  614. **Client Configuration (SonarQube Server):**
  615. ```json
  616. {
  617. "mcpServers": {
  618. "sonarqube-https": {
  619. "url": "https://your-server:8443/mcp",
  620. "headers": {
  621. "Authorization": "Bearer <your-token>",
  622. "SONARQUBE_TOOLSETS": "issues,quality-gates",
  623. "SONARQUBE_READ_ONLY": "true"
  624. }
  625. }
  626. }
  627. }
  628. ```
  629. > **Note:** `SONARQUBE_TOOLSETS` and `SONARQUBE_READ_ONLY` are optional per-request headers that narrow the server-level tool set for that specific request. They can only reduce scope β€” they cannot enable toolsets or lift restrictions beyond what the server was launched with.
  630. **Note:** For local development, use Stdio transport instead (the default). HTTPS Streamable HTTP is intended for multi-user production deployments with proper SSL certificates.
  631. #### Hosted SonarQube Cloud OAuth
  632. OAuth support targets Sonar's hosted SonarQube Cloud MCP service. Use an OAuth-capable MCP client and sign in when prompted; no OAuth server settings are needed in your client configuration. Existing SonarQube token clients remain supported.
  633. The `mcp:tools:read` and `mcp:tools:write` scopes independently control access to read and write tools, subject to your Cloud permissions. Use `list_organizations` and tool `organization` arguments to select an organization.
  634. Self-hosted deployments continue to use SonarQube tokens; OAuth for SonarQube Server is not supported yet.
  635. #### Service Endpoints
  636. When running in **Streamable HTTP** mode (`http` or `https`), the server exposes a few unauthenticated service endpoints in addition to the MCP endpoint at `/mcp`. These are intended for service-to-service use (monitoring, orchestration, client compatibility checks) and do not require an `Authorization` header.
  637. | Endpoint | Method | Description | Example response |
  638. |-----------|--------|-----------------------------------------------------------------------------------------------|-----------------------------------|
  639. | `/health` | `GET` | Liveness probe. Returns `200 OK` with an empty body once the server is accepting requests. | *(empty body)* |
  640. | `/info` | `GET` | Returns the MCP server version as JSON. Useful for verifying the deployed server version. | `{"version":"1.16.0"}` |
  641. These endpoints are not available when running with the **Stdio** transport.
  642. ### Custom Certificates
  643. If your SonarQube Server uses a self-signed certificate or a certificate from a private Certificate Authority (CA), you can add custom certificates to the container that will automatically be installed.
  644. <details>
  645. <summary>Configuration</summary>
  646. #### Using Volume Mount
  647. Mount a directory containing your certificates when running the container:
  648. ```bash
  649. docker run --init --pull=always -i --rm \
  650. -v /path/to/your/certificates/:/usr/local/share/ca-certificates/:ro \
  651. -e SONARQUBE_TOKEN="<token>" \
  652. -e SONARQUBE_URL="<url>" \
  653. sonarsource/sonarqube-mcp
  654. ```
  655. #### Supported Certificate Formats
  656. The container supports the following certificate formats:
  657. - `.crt` files (PEM or DER encoded)
  658. - `.pem` files (PEM encoded)
  659. #### MCP Configuration with Certificates
  660. When using custom certificates, you can modify your MCP configuration to mount the certificates:
  661. ```JSON
  662. {
  663. "sonarqube": {
  664. "command": "docker",
  665. "args": [
  666. "run",
  667. "--init",
  668. "--pull=always",
  669. "-i",
  670. "--rm",
  671. "-v",
  672. "/path/to/your/certificates/:/usr/local/share/ca-certificates/:ro",
  673. "-e",
  674. "SONARQUBE_TOKEN",
  675. "-e",
  676. "SONARQUBE_URL",
  677. "sonarsource/sonarqube-mcp"
  678. ],
  679. "env": {
  680. "SONARQUBE_TOKEN": "<token>",
  681. "SONARQUBE_URL": "<url>"
  682. }
  683. }
  684. }
  685. ```
  686. > **Note:** Running the server [from a JAR](#build) instead of the container? The volume mount above installs certificates into the container's OS trust store, which the server also reads. If you cannot use the OS trust store β€” notably on Windows, where it is not consulted β€” point the JVM at a Java truststore holding the CA certificate: `-Djavax.net.ssl.trustStore=/path/to/truststore.p12 -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=<passphrase>`. It is added on top of the default trusted certificates.
  687. </details>
  688. ### Proxy
  689. The SonarQube MCP Server supports HTTP and SOCKS5 proxies through standard Java proxy system properties.
  690. <details>
  691. <summary>Configuration</summary>
  692. #### HTTP/HTTPS Proxy
  693. You can configure proxy settings using Java system properties. These can be set as environment variables or passed as JVM arguments.
  694. **Common Proxy Properties:**
  695. | Property | Description | Example |
  696. |----------|-------------|---------|
  697. | `http.proxyHost` | HTTP proxy hostname | `proxy.example.com` |
  698. | `http.proxyPort` | HTTP proxy port | `8080` |
  699. | `https.proxyHost` | HTTPS proxy hostname | `proxy.example.com` |
  700. | `https.proxyPort` | HTTPS proxy port | `8443` |
  701. | `http.nonProxyHosts` | Hosts that bypass the proxy (pipe-separated) | `localhost\|127.0.0.1\|*.internal.com` |
  702. **HTTP/HTTPS Proxy Authentication:**
  703. | Property | Description | Example |
  704. |----------|-------------|---------|
  705. | `http.proxyUser` | HTTP proxy username | `myuser` |
  706. | `http.proxyPassword` | HTTP proxy password | `mypassword` |
  707. | `https.proxyUser` | HTTPS proxy username | `myuser` |
  708. | `https.proxyPassword` | HTTPS proxy password | `mypassword` |
  709. #### SOCKS5 Proxy
  710. SOCKS5 proxies are supported.
  711. | Property | Description | Default | Example |
  712. |---------------------------|------------------------------------|---------|--------------|
  713. | `socksProxyHost` | SOCKS5 proxy hostname | β€” | `localhost` |
  714. | `socksProxyPort` | SOCKS5 proxy port | `1080` | `1080` |
  715. | `java.net.socks.username` | SOCKS5 username (if auth required) | β€” | `myuser` |
  716. | `java.net.socks.password` | SOCKS5 password (if auth required) | β€” | `mypassword` |
  717. </details>
  718. ### Client Certificate (Mutual TLS)
  719. If your SonarQube Server requires clients to present a certificate during the TLS handshake (mutual TLS), you can provide a PKCS12 keystore by mounting it into the container and passing its location via `JAVA_OPTS`.
  720. <details>
  721. <summary>Configuration</summary>
  722. #### Using a PKCS12 keystore
  723. Mount your `.p12` or `.pfx` file into the container and set the `JAVA_OPTS` environment variable with the keystore properties:
  724. ```bash
  725. docker run --init --pull=always -i --rm \
  726. -v /path/to/client.p12:/etc/ssl/mcp/client.p12:ro \
  727. -e JAVA_OPTS="-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=<passphrase>" \
  728. -e SONARQUBE_TOKEN="<token>" \
  729. -e SONARQUBE_URL="<url>" \
  730. sonarsource/sonarqube-mcp
  731. ```
  732. > **Note:** The certificate file must be readable by the container process. Check and fix permissions if needed:
  733. > ```bash
  734. > ls -la /path/to/client.p12 # look for -rw-r--r-- (644) or wider
  735. > chmod 644 /path/to/client.p12 # grant read access to the container user
  736. > ```
  737. Omit `-Djavax.net.ssl.keyStorePassword` if the keystore has no passphrase. Note that the passphrase used here would be visible through `docker inspect` or process list.
  738. #### MCP Configuration with a Client Certificate
  739. ```json
  740. {
  741. "sonarqube": {
  742. "command": "docker",
  743. "args": [
  744. "run", "--init", "--pull=always", "-i", "--rm",
  745. "-v", "/path/to/client.p12:/etc/ssl/mcp/client.p12:ro",
  746. "-e", "JAVA_OPTS",
  747. "-e", "SONARQUBE_TOKEN",
  748. "-e", "SONARQUBE_URL",
  749. "sonarsource/sonarqube-mcp"
  750. ],
  751. "env": {
  752. "JAVA_OPTS": "-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=<passphrase>",
  753. "SONARQUBE_TOKEN": "<token>",
  754. "SONARQUBE_URL": "<url>"
  755. }
  756. }
  757. }
  758. ```
  759. #### Using a PKCS12 keystore with a standalone JAR
  760. When running the server [from a JAR](#build), pass the keystore properties as JVM arguments before `-jar`:
  761. ```bash
  762. java \
  763. -Djavax.net.ssl.keyStore=/path/to/client.p12 \
  764. -Djavax.net.ssl.keyStoreType=PKCS12 \
  765. -Djavax.net.ssl.keyStorePassword=<passphrase> \
  766. -jar <path_to_sonarqube_mcp_server_jar>
  767. ```
  768. Omit `-Djavax.net.ssl.keyStorePassword` if the keystore has no passphrase.
  769. #### MCP Configuration with a Client Certificate (JAR)
  770. ```json
  771. {
  772. "sonarqube": {
  773. "command": "java",
  774. "args": [
  775. "-Djavax.net.ssl.keyStore=/path/to/client.p12",
  776. "-Djavax.net.ssl.keyStoreType=PKCS12",
  777. "-Djavax.net.ssl.keyStorePassword=<passphrase>",
  778. "-jar",
  779. "<path_to_sonarqube_mcp_server_jar>"
  780. ],
  781. "env": {
  782. "SONARQUBE_TOKEN": "<token>",
  783. "SONARQUBE_URL": "<url>"
  784. }
  785. }
  786. }
  787. ```
  788. > **Note:** PEM certificate and key files (separate `.crt`/`.key` files) must be converted to PKCS12 format first. Use `openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12` to convert them.
  789. </details>
  790. ## Tools
  791. ### Analysis
  792. - **analyze_code_snippet** - Analyze file content with SonarQube analyzers to identify code quality and security issues. Always analyzes the complete file content for accuracy. Optionally filter results to a specific code snippet.
  793. > **Deprecated:** `analyze_code_snippet` will be removed in a future release. Connect SonarQube for IDE to use `analyze_file_list`, or enable Vortex analysis for your organization to use `run_advanced_code_analysis` (see below).
  794. Usage:
  795. - **With workspace mounted** (recommended): pass `filePath` (project-relative) β€” the server reads the file directly, keeping file content out of the agent context window
  796. - **Without workspace mount**: pass complete `fileContent` for full file analysis (reports all issues)
  797. - Add optional `codeSnippet` to filter results - only issues within the snippet will be reported (snippet location auto-detected)
  798. Parameters:
  799. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  800. - `projectKey` - The SonarQube project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  801. - `filePath` - Project-relative path of the file to analyze (e.g., `src/main/java/MyClass.java`). Used when the workspace is mounted at `/app/mcp-workspace` - _String_
  802. - `fileContent` - Complete file content as a string. Required when workspace is not mounted - _String_
  803. - `codeSnippet` - Code snippet to filter issues (must match content in fileContent) - _String_
  804. - `language` - Language of the code (e.g., 'java', 'python', 'js', 'ts', 'tsx', 'jsx') - _String_
  805. - `scope` - Scope of the file: MAIN or TEST (default: MAIN) - _String_
  806. **Supported Languages:** Java, Kotlin, Python, Ruby, Go, JavaScript (`js`, `jsx`), TypeScript (`ts`, `tsx`), JSP, PHP, XML, HTML, CSS, CloudFormation, Kubernetes, Terraform, Azure Resource Manager, Ansible, Docker, Secrets detection
  807. **When integration with SonarQube for IDE is enabled:** _(these two tools are tagged under both the `analysis` and `ide` toolsets)_
  808. - **analyze_file_list** - Analyze files in the current working directory using SonarQube for IDE. This tool connects to a running SonarQube for IDE instance to perform code quality analysis on a list of files.
  809. - `file_absolute_paths` - List of absolute file paths to analyze - _Required String[]_
  810. - **toggle_automatic_analysis** - Enable or disable SonarQube for IDE automatic analysis. When enabled, SonarQube for IDE will automatically analyze files as they are modified in the working directory. When disabled, automatic analysis is turned off.
  811. - `enabled` - Enable or disable the automatic analysis - _Required Boolean_
  812. On SonarQube Server, stdio lists Vortex context tools and `run_advanced_code_analysis` when both the CAG and A3S hubs are entitled.
  813. **When Vortex analysis is available**:
  814. > Requires having the workspace mounted at `/app/mcp-workspace`
  815. - **run_advanced_code_analysis** - Run Vortex analysis on a single file. SonarQube Server uses the nil UUID placeholder.
  816. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  817. - `projectKey` - The key of the project - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  818. - `branch` - Branch name used to retrieve the latest analysis context - _Required String_
  819. - `filePath` - Project-relative path of the file to analyze (e.g., `src/main/java/MyClass.java`). - _Required String_
  820. - `fileScope` - Defines in which scope the file originates from: 'MAIN' or 'TEST' (default: MAIN) - _String_
  821. ### Coverage
  822. - **search_files_by_coverage** - Search for files in a project sorted by coverage (ascending - worst coverage first). This tool helps identify files that need test coverage improvements.
  823. - `projectKey` - The project key to search in - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  824. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  825. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  826. - `maxCoverage` - Maximum coverage threshold (0-100). Only return files with coverage <= this value - _Number_
  827. - `pageIndex` - Page index (1-based, default: 1) - _Number_
  828. - `pageSize` - Page size (default: 100, max: 500) - _Number_
  829. - **get_file_coverage_details** - Get line-by-line coverage information for a specific file, including which exact lines are uncovered and which have partially covered branches. This tool helps identify precisely where to add test coverage. Use after identifying files with low coverage via search_files_by_coverage.
  830. - `key` - File key (e.g. my_project:src/foo/Bar.java) - _Required String_
  831. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  832. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  833. - `from` - First line to analyze (1-based, default: 1) - _Number_
  834. - `to` - Last line to analyze (inclusive). If not specified, all lines are returned - _Number_
  835. ### Dependency Risks
  836. **Note: Dependency risks require SonarQube Advanced Security. On SonarQube Server, version 2025.4 Enterprise or higher is required.**
  837. - **search_dependency_risks** - Search for software composition analysis issues (dependency risks) of a SonarQube project, paired with releases that appear in the analyzed project, application, or portfolio.
  838. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  839. - `projectKey` - Project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  840. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  841. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  842. - `pageIndex` - Optional page index (1-based, default: 1) - _Integer_
  843. - `pageSize` - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - _Integer_
  844. ### Enterprises
  845. **Note: Enterprises are only available when connecting to SonarQube Cloud.**
  846. - **list_enterprises** - List the enterprises available in SonarQube Cloud that you have access to. Use this tool to discover enterprise IDs that can be used with other tools.
  847. - `enterpriseKey` - Optional enterprise key to filter results - _String_
  848. ### Issues
  849. - **change_sonar_issue_status** - Change the status of a SonarQube issue to "accept", "falsepositive" or to "reopen" an issue.
  850. - `key` - Issue key - _Required String_
  851. - `status` - New issue's status - _Required Enum {"accept", "falsepositive", "reopen"}_
  852. - `comment` - Optional comment explaining the status change - _String_
  853. - **search_sonar_issues_in_projects** - Search for SonarQube issues in my organization's projects.
  854. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  855. - `projectKeys` - Optional list of SonarQube project keys - _String[]_
  856. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  857. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  858. - `severities` - Optional list of severities to filter by. Possible values: INFO, LOW, MEDIUM, HIGH, BLOCKER - _String[]_
  859. - `impactSoftwareQualities` - Optional list of software qualities to filter by. Possible values: MAINTAINABILITY, RELIABILITY, SECURITY - _String[]_
  860. - `issueStatuses` - Optional list of issue statuses to filter by. Possible values: OPEN, CONFIRMED, FALSE_POSITIVE, ACCEPTED, FIXED, IN_SANDBOX - _String[]_
  861. - `tags` - Optional list of issue tags to filter by. Tags are lowercase - _String[]_
  862. - `inNewCodePeriod` - Only return issues in the new code period. Requires exactly one entry across `projectKeys` and `files` - _Boolean_
  863. - `issueKey` - Optional issue key to fetch a specific issue - _String_
  864. - `pageIndex` - Optional 1-based page index (default: 1) - _Integer_
  865. - `pageSize` - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - _Integer_
  866. ### Security Hotspots
  867. - **search_security_hotspots** - Search for Security Hotspots in a SonarQube project.
  868. - `projectKey` - Project or application key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  869. - `hotspotKeys` - Comma-separated list of specific Security Hotspot keys to retrieve - _String[]_
  870. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  871. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  872. - `files` - Optional list of file paths to filter - _String[]_
  873. - `status` - Optional status filter: TO_REVIEW, REVIEWED - _String_
  874. - `resolution` - Optional resolution filter: FIXED, SAFE, ACKNOWLEDGED - _String_
  875. - `sinceLeakPeriod` - Filter hotspots created since the leak period (new code) - _Boolean_
  876. - `onlyMine` - Show only hotspots assigned to me - _Boolean_
  877. - `pageIndex` - Optional 1-based page index (default: 1) - _Integer_
  878. - `pageSize` - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - _Integer_
  879. - **show_security_hotspot** - Get detailed information about a specific Security Hotspot, including rule details, code context, flows, and comments.
  880. - `hotspotKey` - Security Hotspot key - _Required String_
  881. - **change_security_hotspot_status** - Review a Security Hotspot by changing its status. When marking as REVIEWED, you must specify a resolution (FIXED, SAFE, or ACKNOWLEDGED).
  882. - `hotspotKey` - Security Hotspot key - _Required String_
  883. - `status` - New status - _Required Enum {"TO_REVIEW", "REVIEWED"}_
  884. - `resolution` - Resolution when status is REVIEWED - _Enum {"FIXED", "SAFE", "ACKNOWLEDGED"}_
  885. - `comment` - Optional review comment - _String_
  886. ### Languages
  887. - **list_languages** - List all programming languages supported in this SonarQube instance.
  888. - `q` - Optional pattern to match language keys/names against - _String_
  889. ### Measures
  890. - **get_component_measures** - Get SonarQube measures for a component (project, directory, file).
  891. - `projectKey` - The project key - _Required String when `SONARQUBE_PROJECT_KEY` is not configured_
  892. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  893. - `metricKeys` - Optional metric keys to retrieve (e.g. ncloc, complexity, violations, coverage) - _String[]_
  894. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  895. ### Metrics
  896. - **search_metrics** - Search for SonarQube metrics.
  897. - `pageIndex` - Optional 1-based page index (default: 1) - _Integer_
  898. - `pageSize` - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 100) - _Integer_
  899. ### Portfolios
  900. - **list_portfolios** - List enterprise portfolios available in SonarQube with filtering and pagination options.
  901. **For SonarQube Server:**
  902. - `q` - Optional search query to filter portfolios by name or key - _String_
  903. - `favorite` - If true, only returns favorite portfolios - _Boolean_
  904. - `pageIndex` - Optional 1-based page number (default: 1) - _Integer_
  905. - `pageSize` - Optional page size, max 500 (default: 100) - _Integer_
  906. **For SonarQube Cloud:**
  907. - `enterpriseId` - Enterprise uuid. Can be omitted only if 'favorite' parameter is supplied with value true - _String_
  908. - `q` - Optional search query to filter portfolios by name - _String_
  909. - `favorite` - Required to be true if 'enterpriseId' parameter is omitted. If true, only returns portfolios favorited by the logged-in user. Cannot be true when 'draft' is true - _Boolean_
  910. - `draft` - If true, only returns drafts created by the logged-in user. Cannot be true when 'favorite' is true - _Boolean_
  911. - `pageIndex` - Optional index of the page to fetch (default: 1) - _Integer_
  912. - `pageSize` - Optional size of the page to fetch (default: 50) - _Integer_
  913. ### Projects
  914. - **list_organizations** - List SonarQube Cloud organizations that a user is a member of, including keys, names, IDs, and UUIDs. Use a returned key as `organization` on subsequent tools.
  915. - **search_my_sonarqube_projects** - Find SonarQube projects. The response is paginated.
  916. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  917. - `pageIndex` - Optional 1-based page index (default: 1) - _Integer_
  918. - `pageSize` - Optional page size. Must be greater than 0 and less than or equal to 500 (default: 500) - _Integer_
  919. - `q` - Optional search query to filter projects by name (partial match) or key (exact match) - _String_
  920. - **list_branches** - List analyzed branches for a project.
  921. - **SonarQube Cloud**: returns long-lived (`LONG`) and short-lived (`SHORT`) branches with `type` and `mergeBranch` fields. Optional `branchTypes` filter: `ALL` (default), `LONG`, or `SHORT`.
  922. - **SonarQube Server**: returns all analyzed branches (name, quality gate, analysis date). No `type`, `mergeBranch`, or `branchTypes` filter.
  923. - Use returned branch names as the `branch` parameter on other tools. For pull request analysis, use `list_pull_requests` instead.
  924. - `projectKey` - Project key (e.g. my_project) - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  925. - `branchTypes` - _(SonarQube Cloud only)_ Optional filter: `ALL` (default), `LONG`, or `SHORT` - _Enum {"ALL", "LONG", "SHORT"}_
  926. - **list_pull_requests** - List all pull requests for a project. Use this tool to discover pull requests for PR-decorated analysis (coverage, issues, quality gate). Returns the pull request key/ID which can be used with other tools. For branch-based analysis without pull requests, use `list_branches` instead.
  927. - `projectKey` - Project key (e.g. my_project) - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  928. ### Quality Gates
  929. - **get_project_quality_gate_status** - Get the Quality Gate Status for the SonarQube project.
  930. - `analysisId` - Optional analysis ID - _String_
  931. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  932. - `projectId` - Optional project ID - _String_
  933. - `projectKey` - Optional project key - _String_
  934. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  935. - **list_quality_gates** - List all quality gates in my SonarQube.
  936. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  937. ### Rules
  938. - **show_rule** - Shows detailed information about a SonarQube rule.
  939. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  940. - `key` - Rule key - _Required String_
  941. ### Duplications
  942. - **search_duplicated_files** - Search for files with code duplications in a SonarQube project. By default, automatically fetches all duplicated files across all pages (up to 10,000 files max). Returns only files with duplications.
  943. - `projectKey` - Project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  944. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  945. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  946. - `pageSize` - Optional number of results per page for manual pagination (max: 500). If not specified, auto-fetches all duplicated files - _Integer_
  947. - `pageIndex` - Optional page number for manual pagination (starts at 1). If not specified, auto-fetches all duplicated files - _Integer_
  948. - **get_duplications** - Get duplications for a file. Require Browse permission on file's project.
  949. - `key` - File key - _Required String_
  950. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  951. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  952. ### Sources
  953. - **get_raw_source** - Get source code as raw text from SonarQube. Require 'See Source Code' permission on file.
  954. - `key` - File key - _Required String_
  955. - `branch` - Optional branch name for branch-based analysis. Use `list_branches` to discover valid names - _String_
  956. - `pullRequest` - Optional pull request key/ID. Use `list_pull_requests` to discover valid keys - _String_
  957. - **get_scm_info** - Get SCM information of SonarQube source files. Require See Source Code permission on file's project.
  958. - `key` - File key - _Required String_
  959. - `commits_by_line` - Group lines by SCM commit if value is false, else display commits for each line - _String_
  960. - `from` - First line to return. Starts at 1 - _Number_
  961. - `to` - Last line to return (inclusive) - _Number_
  962. ### System
  963. **Note: System tools are only available when connecting to SonarQube Server.**
  964. - **get_system_health** - Get the health status of SonarQube Server instance. Returns GREEN (fully operational), YELLOW (usable but needs attention), or RED (not operational).
  965. - **get_system_info** - Get detailed information about SonarQube Server system configuration including JVM state, database, search indexes, and settings. Requires 'Administer' permissions.
  966. - **get_system_logs** - Get SonarQube Server system logs in plain-text format. Requires system administration permission.
  967. - `name` - Optional name of the logs to get. Possible values: access, app, ce, deprecation, es, web. Default: app - _String_
  968. - **ping_system** - Ping the SonarQube Server system to check if it's alive. Returns 'pong' as plain text.
  969. - **get_system_status** - Get state information about SonarQube Server. Returns status (STARTING, UP, DOWN, RESTARTING, DB_MIGRATION_NEEDED, DB_MIGRATION_RUNNING), version, and id.
  970. ### Webhooks
  971. - **create_webhook** - Create a new webhook for the SonarQube organization or project. Requires 'Administer' permission on the specified project, or global 'Administer' permission.
  972. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  973. - `name` - Webhook name - _Required String_
  974. - `url` - Webhook URL - _Required String_
  975. - `projectKey` - Optional project key for project-specific webhook - _String_
  976. - `secret` - Optional webhook secret for securing the webhook payload - _String_
  977. - **list_webhooks** - List all webhooks for the SonarQube organization or project. Requires 'Administer' permission on the specified project, or global 'Administer' permission.
  978. - `organization` - SonarQube Cloud organization key - _Optional String, Cloud only_
  979. - `projectKey` - Optional project key to list project-specific webhooks - _String_
  980. ### Context Augmentation
  981. <details>
  982. <summary>Architecture Tools</summary>
  983. - **search_by_signature_patterns** - Find code elements (classes, methods, interfaces, ...) by their declaration signatures using regex patterns.
  984. - `include_code_regex_list` - List of regex patterns to match against signatures - _Required String[]_
  985. - `exclude_code_regex_list` - List of regex patterns to exclude from results - _String[]_
  986. - `include_glob` - File filter glob pattern (e.g., `*.java`) - _String_
  987. - `exclude_glob` - File exclusion glob pattern - _String_
  988. - `fields` - Comma-separated list of fields to include in the response - _String_
  989. - `limit` - Maximum number of results to return (default: 10) - _Integer_
  990. - `regex_lists_operator` - How to combine multiple patterns: `OR` (default) or `AND` - _String_
  991. - **search_by_body_patterns** - Find code elements by their implementation body using regex patterns. Useful for locating where APIs or patterns are actually used.
  992. - `include_code_regex_list` - List of regex patterns to match in code bodies - _Required String[]_
  993. - `exclude_code_regex_list` - List of regex patterns to exclude from results - _String[]_
  994. - `include_glob` - File filter glob pattern - _String_
  995. - `exclude_glob` - File exclusion glob pattern - _String_
  996. - `fields` - Comma-separated list of fields to include in the response - _String_
  997. - `limit` - Maximum number of results to return (default: 10) - _Integer_
  998. - `regex_lists_operator` - How to combine multiple patterns: `OR` (default) or `AND` - _String_
  999. - **get_upstream_call_flow** - Trace what functions call a given function. Useful for finding all callers and entry points, and understanding what breaks if a signature changes.
  1000. - `fqn` - Fully qualified name of the function - _Required String_
  1001. - `depth` - Call chain depth (0=function only, 1=direct callers, etc.) - _Integer_
  1002. - `fields` - Comma-separated list of fields to include in the response - _String_
  1003. - **get_downstream_call_flow** - Trace what functions a given function calls. Useful for impact analysis and understanding execution flow.
  1004. - `fqn` - Fully qualified name of the function - _Required String_
  1005. - `depth` - Call chain depth (0=function only, 1=direct callees, etc.) - _Integer_
  1006. - `fields` - Comma-separated list of fields to include in the response - _String_
  1007. - **get_source_code** - Get complete source code (signature and body) for a code element by its fully qualified name.
  1008. - `fqn` - Fully qualified name of the element - _Required String_
  1009. - `fields` - Comma-separated list of fields to include in the response - _String_
  1010. - **get_type_hierarchy** - Get the full inheritance hierarchy for a class-like structure (class, interface, enum, record, exception, struct). Essential for understanding inheritance trees and refactoring.
  1011. - `fqn` - Fully qualified name of the class-like structure - _Required String_
  1012. - `fields` - Comma-separated list of fields to include in the response - _String_
  1013. - **get_references** - Get direct inbound and outbound code references for a class or module. Returns only direct (non-transitive) references.
  1014. - `fqn` - Fully qualified name of the class or module - _Required String_
  1015. - `fields` - Comma-separated list of fields to include in the response - _String_
  1016. - **get_current_architecture** - Get a hierarchical architecture graph filtered by path prefix and depth. Useful for exploring module structure and high-level dependencies.
  1017. - `depth` - Hierarchy depth (0=root only, 1=root + children, etc.) - _Required Integer_
  1018. - `path_prefix` - Optional path prefix to filter nodes (e.g., `com.example.service`) - _String_
  1019. - `ecosystem` - Optional ecosystem to filter by (`java`, `cs`, `py`, `js`, `ts`) - _String_
  1020. - **get_intended_architecture** - Get user-defined architectural constraints specifying which modules are allowed to depend on others.
  1021. </details>
  1022. <details>
  1023. <summary>Guidelines Tools</summary>
  1024. - **get_guidelines** - Get coding guidelines based on SonarQube project issues, catalog categories, or a combination of both.
  1025. - `mode` - Guidelines retrieval mode: `project_based`, `category_based`, or `combined` - _Required String_
  1026. - `categories` - List of category names (required for `category_based` and `combined` modes) - _String[]_
  1027. - `languages` - List of target languages in SonarQube repository key format (required when `categories` is provided) - _String[]_
  1028. - `file_paths` - Optional list of file paths to filter guidelines by - _String[]_
  1029. </details>
  1030. <details>
  1031. <summary>Third-party Dependency Tools</summary>
  1032. - **check_dependency** - Check a third-party dependency for security vulnerabilities, supply-chain malware, and license compliance before adding or updating it.
  1033. - `purl` - Package URL (purl) with version, per [purl-spec](https://github.com/package-url/purl-spec). Format: `pkg:<type>/<namespace>/<name>@<version>` (e.g. `pkg:npm/lodash@4.17.21`, `pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1`, `pkg:pypi/django@3.2.0`) - _Required String_
  1034. </details>
  1035. <details>
  1036. <summary>Context Augmentation Environment Variables</summary>
  1037. | Variable | Description | Required | Default |
  1038. | ------------------------- | -------------------------------------------------------------------------------------- | -------- | ----------------------- |
  1039. | `SONARQUBE_URL` | SonarQube Cloud URL | Yes | `https://sonarcloud.io` |
  1040. | `SONARQUBE_TOKEN` | Authentication token | Yes | None |
  1041. | `SONARQUBE_ORG` | Cloud organization; passed to the proxy from startup configuration or unique detection | No | None |
  1042. | `SONARQUBE_PROJECT_KEY` | Project key on SonarQube Cloud | Yes | None |
  1043. | `SONAR_SQ_BRANCH` | Explicit SonarQube branch override * | No | None |
  1044. | `SONARQUBE_DEBUG_ENABLED` | Activate debug logging (for troubleshooting) | No | False |
  1045. | `SONAR_LOG_LEVEL` | Logging verbosity (`TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`) | No | `INFO` |
  1046. * To be provided when not using git, or when the git branch name doesn't match the branch name in SonarQube.
  1047. </details>
  1048. <details>
  1049. <summary>Project-Specific Configuration (Recommended)</summary>
  1050. First, export the `SONARQUBE_TOKEN` [environment variable](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/environment-variables#common-variables) with a valid [Personal Access Token (PAT)](https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens) for your project.
  1051. ```bash
  1052. # macOS/Linux (Bash/Zsh)
  1053. export SONARQUBE_TOKEN="{<YourUserToken>}"
  1054. ```
  1055. Then, mount the project workspace to give the Context Augmentation server direct access to your source files:
  1056. ```json
  1057. {
  1058. "mcpServers": {
  1059. "sonarqube-mcp-server": {
  1060. "command": "docker",
  1061. "args": [
  1062. "run", "-i", "--rm", "--pull=always",
  1063. "-e", "SONARQUBE_URL",
  1064. "-e", "SONARQUBE_TOKEN",
  1065. "-e", "SONARQUBE_ORG",
  1066. "-e", "SONARQUBE_PROJECT_KEY",
  1067. "-e", "SONARQUBE_TOOLSETS",
  1068. "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
  1069. "sonarsource/sonarqube-mcp"
  1070. ],
  1071. "env": {
  1072. "SONARQUBE_URL": "https://sonarcloud.io",
  1073. "SONARQUBE_ORG": "<YourOrganizationKey>",
  1074. "SONARQUBE_PROJECT_KEY": "<YourProjectKey>",
  1075. "SONARQUBE_TOOLSETS": "cag"
  1076. }
  1077. }
  1078. }
  1079. }
  1080. ```
  1081. **Important**: In a project-scoped config, do not put `SONARQUBE_TOKEN` in the env block. Export it as an environment variable (`export SONARQUBE_TOKEN=...`). Docker will forward it into the container via `-e SONARQUBE_TOKEN`.
  1082. </details>
  1083. ### Agentic Readiness
  1084. **Note: Agentic Readiness tools are only available on SonarQube Cloud and require the feature to be enabled for your organization.**
  1085. The feature flag is checked at startup in stdio mode. Over HTTP/HTTPS, add `agentic-readiness` to the server's `SONARQUBE_TOOLSETS` to enable the tools.
  1086. - **start_agentic_readiness_assessment** - Start an agentic readiness assessment for a project. Returns immediately with status `PENDING` and an `assessmentId`. Use `get_agentic_readiness_assessment` to poll for results.
  1087. - `projectKey` - The project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  1088. - `branch` - Branch to assess. Omit to use the project's default branch - _String_
  1089. - **get_agentic_readiness_assessment** - Retrieve the result of an assessment. Re-call with the same `assessmentId` until status is `COMPLETED`, `FAILED`, or `INTERRUPTED`. When completed, returns the overall level and a per-pillar breakdown with recommended actions and evidence.
  1090. - `assessmentId` - The assessment ID returned by `start_agentic_readiness_assessment` - _Required String_
  1091. - **list_agentic_readiness_assessments** - List all assessments for a project, newest first. Use `get_agentic_readiness_assessment` for full pillar-level results.
  1092. - `projectKey` - The project key to list assessments for - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  1093. - `branch` - Filter assessments by branch name. Omit to list assessments for all branches - _String_
  1094. - `pageIndex` - 1-based page index (default: 1) - _Number_
  1095. - `pageSize` - Number of items per page, max 100 (default: 50) - _Number_
  1096. ### Architecture
  1097. **Note: Enable these tools with `SONARQUBE_TOOLSETS=architecture` in stdio or HTTP/HTTPS mode. SonarQube Cloud requires a Team or Enterprise plan. SonarQube Server requires version 2026.6 or later and a Developer edition or higher; the tools are not available on older versions or Community Build.** See [architecture workflows and recovery](docs/architecture.md).
  1098. - **architecture_get** - Read current dependencies, intended architecture, project directives, findings, or per-language finding counts.
  1099. - `target` - `current`, `intended`, `directives`, `findings` or `summary` (Cloud only); other targets depend on the MCP and Server build - _Required Enum_
  1100. - `projectKey` - The project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  1101. - `organization` - SonarQube Cloud organization key when none is configured - _Optional String, Cloud only_
  1102. - `component` - Exact current node key or intended group path; top level when omitted - _String_
  1103. - `depth` - Current/intended only: levels below the start; default 1 for current, all for intended - _Number_
  1104. - `language` - Current/intended/findings/summary only: `java`, `cs`, `js`, `ts` or `py` - _Enum_
  1105. - `directiveId` - Full directive by UUID, including description; use instead of paging - _String_
  1106. - `category` / `type` - Findings only: filter deviations, flaws or smells by their advertised type - _Enum_
  1107. - `pageIndex` - Directives/Findings: 1-based page index (default: 1) - _Number_
  1108. - `pageSize` - Directives: summaries, default/maximum 50. Findings: default 50, maximum 1000; 0 counts only - _Number_
  1109. - **architecture_set** - Replace the whole intended architecture or create, update and delete project directives. Available on supported Cloud and Server builds when writes are enabled.
  1110. - `target` - `intended` or `directives` - _Required Enum_
  1111. - `projectKey` - The project key - _Required String_ _(Ignored when `SONARQUBE_PROJECT_KEY` is defined)_
  1112. - `organization` - SonarQube Cloud organization key when none is configured - _Optional String, Cloud only_
  1113. - `model` - JSON string: complete intended export or `models` array (omitted content is removed), or directive changes with `create`, `update` and `delete` arrays - _Required String_
  1114. - `dryRun` - `true` to preview, `false` to apply - _Required Boolean_
  1115. - `revision` - Intended only: revision from `architecture_get`; defaults to the complete export's revision. Required when applying a clear - _String_
  1116. ## Example Prompts
  1117. Once you've set up the SonarQube MCP Server, here are some example prompts for common real-world scenarios:
  1118. <details>
  1119. <summary>Fixing a Failing Quality Gate</summary>
  1120. ```
  1121. My quality gate is failing for my project. Can you help me understand why and fix the most critical issues?
  1122. ```
  1123. ```
  1124. The quality gate on my feature branch is red. What do I need to fix to get it passing before I can merge to main?
  1125. ```
  1126. </details>
  1127. <details>
  1128. <summary>Pre-Release and Pre-Merge Checks</summary>
  1129. ```
  1130. I'm about to merge my pull request <#247> for the <web-app> project. Can you check if there are any quality issues I should address first?
  1131. ```
  1132. ```
  1133. We're deploying to production tomorrow. Can you check the quality gate status and alert me to any critical issues in this branch?
  1134. ```
  1135. </details>
  1136. <details>
  1137. <summary>Improving Code Quality</summary>
  1138. ```
  1139. I want to reduce technical debt in my project. What are the top issues I should prioritize?
  1140. ```
  1141. ```
  1142. Our code coverage dropped below 70%. Can you identify which files have the lowest coverage and help me improve it?
  1143. ```
  1144. </details>
  1145. <details>
  1146. <summary>Understanding and Fixing Issues</summary>
  1147. ```
  1148. I have 15 new code smells in my latest commit. Can you explain what they are and help me fix them?
  1149. ```
  1150. ```
  1151. SonarQube flagged a critical security vulnerability in <AuthController.java>. What's the issue and how do I fix it?
  1152. ```
  1153. </details>
  1154. <details>
  1155. <summary>Security and Dependency Management</summary>
  1156. ```
  1157. We need to pass a security audit. Can you check all our projects for security vulnerabilities and create a prioritized list of what needs to be fixed?
  1158. ```
  1159. ```
  1160. Are there any known vulnerabilities in our dependencies? Check this project for dependency risks.
  1161. ```
  1162. </details>
  1163. <details>
  1164. <summary>Code Review Assistance</summary>
  1165. ```
  1166. I just wrote this authentication function. Can you analyze it for security issues and code quality problems before I commit?
  1167. ```
  1168. ```
  1169. Review the changes in <src/database/migrations> for any potential bugs or security issues.
  1170. ```
  1171. </details>
  1172. <details>
  1173. <summary>Project Health Monitoring</summary>
  1174. ```
  1175. Give me a health report for my project: quality gate status, number of bugs, Security Hotspots, and code coverage.
  1176. ```
  1177. ```
  1178. Compare code quality between our main branch and the develop branch. Are we introducing new issues?
  1179. ```
  1180. </details>
  1181. <details>
  1182. <summary>Team Collaboration</summary>
  1183. ```
  1184. What are the most common rule violations across all our projects? We might need to update our coding standards.
  1185. ```
  1186. ```
  1187. Show me all the issues that were marked as false positives in the last month. Are we seeing patterns that suggest our rules need adjustment?
  1188. ```
  1189. </details>
  1190. ## Build
  1191. Prefer the [sonarsource/sonarqube-mcp](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags) container image.
  1192. To run the server as a standalone JAR without Docker, download a pre-built release from the [SonarSource binaries repository](https://binaries.sonarsource.com/?prefix=Distribution/sonarqube-mcp-server/). Every released version is published there as `sonarqube-mcp-server-<version>.jar` (for example, `sonarqube-mcp-server-1.19.0.2785.jar`).
  1193. <details>
  1194. <summary>Run from JAR</summary>
  1195. Download the JAR for the version you want from the [binaries repository](https://binaries.sonarsource.com/?prefix=Distribution/sonarqube-mcp-server/), then configure your MCP client to run it with Java 21 or later:
  1196. * To connect with SonarQube Cloud:
  1197. ```JSON
  1198. {
  1199. "sonarqube": {
  1200. "command": "java",
  1201. "args": [
  1202. "-jar",
  1203. "<path_to_sonarqube_mcp_server_jar>"
  1204. ],
  1205. "env": {
  1206. "STORAGE_PATH": "<path_to_your_mcp_storage>",
  1207. "SONARQUBE_TOKEN": "<token>",
  1208. "SONARQUBE_ORG": "<org>"
  1209. }
  1210. }
  1211. }
  1212. ```
  1213. * To connect with SonarQube Server:
  1214. ```JSON
  1215. {
  1216. "sonarqube": {
  1217. "command": "java",
  1218. "args": [
  1219. "-jar",
  1220. "<path_to_sonarqube_mcp_server_jar>"
  1221. ],
  1222. "env": {
  1223. "STORAGE_PATH": "<path_to_your_mcp_storage>",
  1224. "SONARQUBE_TOKEN": "<token>",
  1225. "SONARQUBE_URL": "<url>"
  1226. }
  1227. }
  1228. }
  1229. ```
  1230. </details>
  1231. <details>
  1232. <summary>Build from source</summary>
  1233. SonarQube MCP Server requires a Java Development Kit (JDK) version 21 or later to build.
  1234. Run the following Gradle command to clean the project and build the application:
  1235. ```bash
  1236. ./gradlew clean build -x test
  1237. ```
  1238. The JAR file will be created in `build/libs/`.
  1239. After adding or updating dependencies, regenerate the lock files:
  1240. ```bash
  1241. ./gradlew :dependencies --write-locks
  1242. ./gradlew :its:dependencies --write-locks
  1243. ```
  1244. Use the **Run from JAR** configuration above, pointing `<path_to_sonarqube_mcp_server_jar>` to the JAR in `build/libs/`.
  1245. </details>
  1246. ## Troubleshooting
  1247. Application logs are written to the `STORAGE_PATH/logs/mcp.log` file by default. To disable file logging entirely, set `SONARQUBE_LOG_TO_FILE_DISABLED=true`.
  1248. ### Common Issues
  1249. #### "SonarQube server version is not supported"
  1250. The MCP server checks the connected SonarQube Server version during startup. If the instance is older than **2025.1** (SQS) or **25.1** (SQCB), startup fails with:
  1251. ```text
  1252. SonarQube server version is not supported, minimal version is SQS 2025.1 or SQCB 25.1
  1253. ```
  1254. **Solution:** Upgrade SonarQube Server to a supported release. This check applies only when connecting to SonarQube Server (`SONARQUBE_URL` without `SONARQUBE_ORG`), not to SonarQube Cloud.
  1255. #### "Feature is not working" or "Missing tools/functionality"
  1256. You may be running an outdated Docker image. Docker caches images locally, so you won't automatically receive updates.
  1257. **Solution:** Update to the latest version:
  1258. ```bash
  1259. docker pull sonarsource/sonarqube-mcp
  1260. ```
  1261. After pulling the latest image, restart your MCP client to use the updated version.
  1262. Optionally, add the `--pull=always` flag to your docker run command to always check for and pull the latest version:
  1263. ```bash
  1264. docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp
  1265. ```
  1266. #### "I want to pin to a specific version"
  1267. Browse available tags at [sonarsource/sonarqube-mcp](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags) and reference the version you want:
  1268. ```bash
  1269. docker pull sonarsource/sonarqube-mcp:1.19.0.2785
  1270. docker run --init -i --rm \
  1271. -e SONARQUBE_TOKEN -e SONARQUBE_ORG \
  1272. sonarsource/sonarqube-mcp:1.19.0.2785
  1273. ```
  1274. In your MCP client config, use `sonarsource/sonarqube-mcp:<version>` instead of `sonarsource/sonarqube-mcp` and remove `--pull=always` so Docker does not silently upgrade the image.
  1275. ## Data and telemetry
  1276. This server collects anonymous usage data and sends it to SonarSource to help improve the product. No source code or IP address is collected, and SonarSource does not share the data with anyone else. Collection of telemetry can be disabled with the following system property or environment variable: `TELEMETRY_DISABLED=true`. Click [here](telemetry-sample.md) to see a sample of the data that are collected.
  1277. ## License
  1278. Copyright 2025 SonarSource.
  1279. Licensed under the [SONAR Source-Available License v1.0](https://www.sonarsource.com/license/ssal/). Using the SonarQube MCP Server in compliance with this documentation is a Non-Competitive Purpose and so is allowed under the SSAL.
  1280. Your use of SonarQube via MCP is governed by the [SonarQube Cloud Terms of Service](https://www.sonarsource.com/legal/sonarcloud/terms-of-service/) or [SonarQube Server Terms and Conditions](https://www.sonarsource.com/legal/sonarqube/terms-and-conditions/), including use of the Results Data solely for your internal software development purposes.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.