sonar-mcp-server

SonarQube MCP 服务

SonarQube MCP 服务是一种模型上下文协议（MCP）服务，可与 SonarQube Server 或 Cloud 无缝集成，用于代码质量和安全检查。 它还支持直接在 Agent 上下文中分析代码片段。

请从快速设置开始，或进一步了解 SonarQube 产品系列。

快速设置

🚀 生成配置

最快的入门方式是使用 SonarQube MCP 服务配置生成器——这是一个交互式工具，可为你首选的 AI Agent 客户端生成可直接使用的配置。

手动设置

如果你更喜欢自行配置，最简单的方法是使用我们的容器镜像 sonarsource/sonarqube-mcp。使用 sonarsource/sonarqube-mcp 可自动更新（通过 --pull=always），也可以固定到某个版本标签（例如 sonarsource/sonarqube-mcp:1.19.0.2785），以便进行可复现的部署。部分版本也会使用与之对应的 SonarQube Server 版本号作为标签，格式为 <SQS major>.<SQS minor>.<patch>（例如 sonarsource/sonarqube-mcp:2026.5.0），其中每次发布针对该 SonarQube Server 版本的 MCP 版本时，补丁号都会递增。如果你想在本地构建，请参阅下文。

**注意：**以下示例使用 docker，但任何兼容 OCI 的容器运行时都适用（例如 Podman、nerdctl）。只需将 docker 替换为你首选的工具即可。

{
  "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>"
      }
    }
  }
}

{
  "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>"
      }
    }
  }
}

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

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

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

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

gemini extensions install https://github.com/SonarSource/sonarqube-agent-plugins

/mcp add

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=<YOUR_TOKEN>,SONARQUBE_ORG=<YOUR_ORG>
Tools: *

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_URL, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=<YOUR_USER_TOKEN>,SONARQUBE_URL=<YOUR_SERVER_URL>
Tools: *

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_ORG",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_TOKEN",
        "SONARQUBE_ORG": "COPILOT_MCP_SONARQUBE_ORG"
      },
      "tools": ["*"]
    }
  }
}

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_USER_TOKEN",
        "SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL"
      },
      "tools": ["*"]
    }
  }
}

{
  "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>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "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>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "sonarqube_token": "YOUR_SONARQUBE_TOKEN",
  "sonarqube_org": "SONARQUBE_ORGANIZATION_KEY",
  "docker_path": "DOCKER_PATH"
}

{
  "sonarqube_token": "YOUR_SONARQUBE_USER_TOKEN",
  "sonarqube_url": "YOUR_SONARQUBE_SERVER_URL",
  "docker_path": "DOCKER_PATH"
}

💡 提示： 我们建议定期拉取最新镜像，或在报告问题前拉取，以确保使用最新的功能和修复。

手动安装

你可以将以下代码片段复制到 MCP 服务配置文件中，手动安装 SonarQube MCP 服务：

• 连接到 SonarQube Cloud：

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

• 连接到 SonarQube Server：

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

与 SonarQube for IDE 集成

SonarQube MCP Server 可与 SonarQube for IDE 集成，进一步优化开发工作流，并直接在 IDE 中提供更出色的代码分析和洞察。

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_ORG",
      "-e",
      "SONARQUBE_IDE_PORT",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_ORG": "<org>",
      "SONARQUBE_IDE_PORT": "<64120-64130>"
    }
  }
}

配置

根据你的环境，需要提供特定的环境变量。

基础配置

运行 MCP 服务时，应添加以下变量：

工作区挂载（减少上下文膨胀）

默认情况下，分析工具 analyze_code_snippet 要求 Agent 将完整文件内容作为 fileContent 参数传入。对于大型文件，或在一次会话中分析多个文件时，这会显著增加上下文窗口的占用和成本。

解决方案： 将项目目录挂载到容器中的 /app/mcp-workspace。检测到此挂载后，服务会通过项目相对路径参数 filePath 直接从磁盘读取文件，文件内容不会经过 Agent 上下文。

{
  "args": [
    "run", "-i", "--rm", "--init", "--pull=always",
    "-e", "SONARQUBE_TOKEN",
    "-e", "SONARQUBE_ORG",
    "-v", "/path/to/your/project:/app/mcp-workspace",
    "sonarsource/sonarqube-mcp"
  ]
}

挂载后，分析工具会通过 filePath 直接读取文件，无需提供 fileContent。

通过 stdio 使用时，分析方式会在启动时确定（受已启用工具集的限制）：

• SonarQube Cloud： 挂载工作区且至少有一个获授权组织时，使用 Vortex 分析（run_advanced_code_analysis）；否则使用本地分析。Vortex 分析仅接受获授权的组织。
• SonarQube Server： 对获授权的实例使用 Vortex 分析（需要挂载工作区）；对不支持 Vortex 的实例使用本地分析。

本地分析会使用已连接的 SonarQube for IDE，或使用 analyze_code_snippet。未挂载工作区时，代码片段分析需要提供 fileContent。

在 Cloud 上，SONARQUBE_ORG 会将授权检查限定在该组织。若要对所有组织使用代码片段分析，请设置 SONARQUBE_FORCE_LOCAL_ANALYSIS=true，启用 analysis 工具集，然后重启。此设置对 Server 无效。

通过 HTTP/HTTPS 使用时，Server 支持在启动时提供 SONARQUBE_TOKEN 进行代码片段分析；Cloud 不提供分析工具。

选择性启用工具

MCP 客户端会在每次对话中，将所有已启用工具的名称、描述和输入架构加载到 Agent 的上下文中。通过 SONARQUBE_TOOLSETS 限制此列表，可以减少上下文占用和每次会话的令牌成本。

默认情况下，仅启用重要的工具集。仅在需要时启用其他工具集。

docker run --init --pull=always -i --rm \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_ORG="<org>" \
  -e SONARQUBE_TOOLSETS="analysis,issues,quality-gates" \
  sonarsource/sonarqube-mcp

docker run --init --pull=always -i --rm \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_ORG="<org>" \
  -e SONARQUBE_READ_ONLY="true" \
  sonarsource/sonarqube-mcp

SonarQube Cloud

对于 stdio，请配置以下环境变量：

示例：

• SonarQube Cloud：仅需 SONARQUBE_TOKEN。设置 SONARQUBE_ORG 后可固定组织。
• SonarQube Cloud US：设置 SONARQUBE_TOKEN 和 SONARQUBE_URL=https://sonarqube.us；SONARQUBE_ORG 为可选项。

SonarQube Server

版本要求： 必须使用 SonarQube Server 2025.1（SQS）、SonarQube Community Build 25.1 或更高版本。启动时，MCP 服务会读取已连接实例的版本；如果版本过旧（例如旧版 9.x/10.x Server 版本和 24.x Community Build），则会报错退出。SonarQube Cloud 不受此检查限制。

⚠️ 连接 SonarQube Server 需要使用 USER 类型的令牌；使用项目令牌或全局令牌将无法正常工作。

💡 配置提示（stdio 模式）： 未指定 URL 的令牌默认连接 SonarQube Cloud。连接 SonarQube Server 或其他 Cloud 区域时，请设置 SONARQUBE_URL。设置 SONARQUBE_ORG 后，将固定使用相应的 Cloud 组织。

在 stdio 模式下，设置 SONARQUBE_ORG 会固定使用相应的 Cloud 组织。工具架构中会省略 organization 参数，并拒绝此参数；设置 SONARQUBE_PROJECT_KEY 时，projectKey 参数也会如此处理。

如果未设置 SONARQUBE_ORG，Agent 可以调用 list_organizations，发现用户帐户可访问的组织键、名称、ID 和 UUID，然后在支持组织的工具中将组织键作为可选的 organization 参数传入。stdio 模式会将唯一检测到的组织保留为默认组织；如果未检测到组织或检测到多个组织，则不会确定默认组织。工具参数仅对该次调用生效，不会更改检测到的默认组织。代码片段配置文件和规则查询会使用该次调用所选的组织。

对于 HTTP/HTTPS 令牌请求，为保持兼容性，仍支持服务级别的 SONARQUBE_ORG，但此设置已弃用，启动时会记录警告。它会为所有请求固定使用相应的组织，并拒绝客户端组织标头和工具 organization 参数。未配置服务组织时，可选的客户端 SONARQUBE_ORG 标头会为该请求固定使用相应的组织，并禁止使用工具 organization 参数。未设置此标头时，请使用工具参数。缺少所有组织信息时，需要组织的工具会提供组织发现指引。组织发现以及 API 只使用资源标识符的工具无需组织参数。支持组织的议题搜索和依赖风险权限检查会使用所选组织。配置 OAuth 后，服务级别的 SONARQUBE_ORG 将被拒绝。OAuth 请求也会拒绝组织标头；请通过工具参数选择组织。

Vortex 上下文工具使用已配置或启动时唯一检测到的组织。运行时组织参数不会重新配置代理上下文引擎；启动时未确定组织则会跳过该代理。内置的 run_advanced_code_analysis 工具会检查每次调用所选组织的 Vortex 综合权限。

传输模式

MCP 规范定义了两种传输机制：Stdio 和 Streamable HTTP。SonarQube MCP Server 同时支持这两种模式：

注意： Streamable HTTP 是当前的 MCP 网络传输方式。早期 MCP 版本中仅支持 SSE 的旧版 HTTP 传输已弃用，不受支持。

1. Stdio（默认 - 建议用于本地开发）

建议在本地开发和单用户设置中使用，大多数 MCP 客户端都采用此模式。

示例 - 使用 SonarQube Cloud 的 Docker：

{
  "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>"
      }
    }
  }
}

2. HTTP（Streamable HTTP）

未加密的 Streamable HTTP 传输。多用户部署请改用 HTTPS。

⚠️ 不建议： 本地开发请使用 Stdio，多用户生产部署请使用 HTTPS（Streamable HTTP）。

注意： HTTP/HTTPS 会通过 Authorization: Bearer <token> 接收用户的 SonarQube 令牌。Sonar 的托管 Cloud 服务也支持 OAuth。对于 SonarQube Cloud 令牌请求，组织按以下方式确定：

• SONARQUBE_ORG 是可选请求标头，用于指定该请求的组织。已弃用的服务级配置会为所有请求固定组织，并拒绝客户端组织标头和工具组织参数。
• 如果服务配置或请求标头都未固定组织，支持组织的工具可以接收可选的 organization 参数。组织已固定时，提供此参数会被拒绝。
• 如果没有默认组织，Agent 可以仅使用令牌调用 list_organizations，然后在后续工具调用中传入所选的键。

客户端也可以通过提供 SONARQUBE_TOOLSETS 和/或 SONARQUBE_READ_ONLY 标头，按请求缩小可见工具范围；这些标头会在服务级配置的基础上进一步筛选，只能缩小范围，不能扩大范围。 请求之间不会维护会话状态。

已弃用： 对于 SonarQube 令牌，仍接受 SONARQUBE_TOKEN 请求标头以保持向后兼容，但将在未来版本中移除。请迁移到 Authorization: Bearer <token>。

3. HTTPS（基于 TLS 的 Streamable HTTP）（推荐用于多用户生产部署）

使用 TLS 加密的安全 Streamable HTTP 传输。需要 SSL 证书。

✅ **生产环境推荐：**通过 Streamable HTTP 为多个用户部署 MCP 服务时，请使用 HTTPS。出于安全考虑，服务默认绑定到 127.0.0.1（localhost）。

SSL 证书配置（可选）：

示例 - 使用 SonarQube Cloud 的 Docker：

**注意：**在容器中运行时，请设置 SONARQUBE_HTTP_HOST=0.0.0.0，让容器监听所有接口，以便运行时的端口映射正常工作；同时设置 SONARQUBE_MCP_IN_CONTAINER=true，告知服务其运行在容器内。官方 Docker 镜像会自动设置后者；使用其他 OCI 运行时（Podman、Kubernetes、Nomad 等）时，请自行设置。主机端口标志控制谁可以从容器外部访问服务。SONARQUBE_HTTP_HOST=0.0.0.0 仅控制服务在容器内监听的位置——浏览器 CORS 仍默认允许 localhost 来源。

对于在本机上本地运行的服务（只能通过 localhost 访问）：

docker run --init --pull=always -p 127.0.0.1:8443:8443 \
  -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  -e SONARQUBE_TRANSPORT=https \
  -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  -e SONARQUBE_HTTP_PORT=8443 \
  sonarsource/sonarqube-mcp

对于可从网络访问的服务（远程部署）：

docker run --init --pull=always -p 8443:8443 \
  -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  -e SONARQUBE_TRANSPORT=https \
  -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  -e SONARQUBE_HTTP_PORT=8443 \
  sonarsource/sonarqube-mcp

客户端配置（SonarQube Cloud）：

对于 SonarQube 令牌请求，可以选择在客户端标头中设置 SONARQUBE_ORG，以固定请求组织；也可以省略此项，通过工具参数选择组织。

{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

客户端配置（SonarQube Server）：

{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

注意：SONARQUBE_TOOLSETS 和 SONARQUBE_READ_ONLY 是可选的逐请求标头，可针对特定请求缩小服务级工具集的范围。它们只能缩小范围，不能启用工具集，也不能解除服务启动时设定的限制。 **注意：**本地开发时，请改用 Stdio 传输（默认方式）。HTTPS Streamable HTTP 适用于配置了有效 SSL 证书的多用户生产部署。

托管的 SonarQube Cloud OAuth

OAuth 支持适用于 Sonar 托管的 SonarQube Cloud MCP 服务。请使用支持 OAuth 的 MCP 客户端，并在出现提示时登录；客户端配置中无需设置 OAuth 服务。现有的 SonarQube 令牌客户端仍受支持。

mcp:tools:read 和 mcp:tools:write 作用域分别控制对读取和写入工具的访问，具体取决于你的 Cloud 权限。使用 list_organizations 和工具的 organization 参数选择组织。

自托管部署继续使用 SonarQube 令牌；目前尚不支持 SonarQube Server 的 OAuth。

服务端点

以 Streamable HTTP 模式（http 或 https）运行时，除了 /mcp 处的 MCP 端点外，服务还会提供一些无需身份验证的服务端点。这些端点供服务间调用（监控、编排、客户端兼容性检查）使用，无需 Authorization 标头。

使用 Stdio 传输时无法使用这些端点。

自定义证书

如果你的 SonarQube Server 使用自签名证书或由私有证书颁发机构（CA）颁发的证书，可以将自定义证书添加到容器中，证书将自动安装。

docker run --init --pull=always -i --rm \
  -v /path/to/your/certificates/:/usr/local/share/ca-certificates/:ro \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_URL="<url>" \
  sonarsource/sonarqube-mcp

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-v",
      "/path/to/your/certificates/:/usr/local/share/ca-certificates/:ro",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

代理

SonarQube MCP Server 通过标准 Java 代理系统属性支持 HTTP 和 SOCKS5 代理。

客户端证书（双向 TLS）

如果你的 SonarQube Server 要求客户端在 TLS 握手期间出示证书（双向 TLS），你可以将 PKCS12 密钥库挂载到容器中，并通过 JAVA_OPTS 传入其位置。

docker run --init --pull=always -i --rm \
  -v /path/to/client.p12:/etc/ssl/mcp/client.p12:ro \
  -e JAVA_OPTS="-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=<passphrase>" \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_URL="<url>" \
  sonarsource/sonarqube-mcp

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run", "--init", "--pull=always", "-i", "--rm",
      "-v", "/path/to/client.p12:/etc/ssl/mcp/client.p12:ro",
      "-e", "JAVA_OPTS",
      "-e", "SONARQUBE_TOKEN",
      "-e", "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "JAVA_OPTS": "-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=<passphrase>",
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

java \
  -Djavax.net.ssl.keyStore=/path/to/client.p12 \
  -Djavax.net.ssl.keyStoreType=PKCS12 \
  -Djavax.net.ssl.keyStorePassword=<passphrase> \
  -jar <path_to_sonarqube_mcp_server_jar>

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-Djavax.net.ssl.keyStore=/path/to/client.p12",
      "-Djavax.net.ssl.keyStoreType=PKCS12",
      "-Djavax.net.ssl.keyStorePassword=<passphrase>",
      "-jar",
      "<path_to_sonarqube_mcp_server_jar>"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

工具

分析

• analyze_code_snippet - 使用 SonarQube 分析器分析文件内容，以识别代码质量和安全问题。为确保准确性，始终分析完整文件内容。也可选择将结果筛选到特定代码片段。

  已弃用： analyze_code_snippet 将在未来版本中移除。请连接 SonarQube for IDE 并使用 analyze_file_list，或为组织启用 Vortex 分析并使用 run_advanced_code_analysis（见下文）。

  用法：

  • 挂载工作区时（推荐）：传入 filePath（相对于项目的路径）——服务会直接读取文件，避免将文件内容放入 Agent 上下文窗口
  • 未挂载工作区时：传入完整的 fileContent 以分析整个文件（报告所有问题）
  • 可添加 codeSnippet 以筛选结果——只报告该片段内的问题（自动检测片段位置）

  参数：

  • projectKey - SonarQube 项目密钥 - 必填 String （定义了 SONARQUBE_PROJECT_KEY 时将忽略）
  • filePath - 要分析文件的相对于项目的路径（例如 src/main/java/MyClass.java）。工作区挂载在 /app/mcp-workspace 时使用 - String
  • fileContent - 作为字符串传入的完整文件内容。未挂载工作区时必填 - String
  • codeSnippet - 用于筛选问题的代码片段（必须与 fileContent 中的内容匹配） - String
  • language - 代码语言（例如，'java'、'python'、'js'、'ts'、'tsx'、'jsx'） - String
  • scope - 文件范围：MAIN 或 TEST（默认值：MAIN） - String

  支持的语言： Java、Kotlin、Python、Ruby、Go、JavaScript（js、jsx）、TypeScript（ts、tsx）、JSP、PHP、XML、HTML、CSS、CloudFormation、Kubernetes、Terraform、Azure Resource Manager、Ansible、Docker、密钥检测

启用 SonarQube for IDE 集成时：（这两个工具同时标记在 analysis 和 ide 工具集下）

• analyze_file_list - 使用 SonarQube for IDE 分析当前工作目录中的文件。此工具连接到正在运行的 SonarQube for IDE 实例，以分析文件列表中的代码质量。

  • file_absolute_paths - 要分析的绝对文件路径列表 - 必填 String[]

• toggle_automatic_analysis - 启用或禁用 SonarQube for IDE 的自动分析。启用后，SonarQube for IDE 会在工作目录中的文件被修改时自动分析文件。禁用后，将关闭自动分析。

  • enabled - 启用或禁用自动分析 - 必填 Boolean

在 SonarQube Server 上，如果 CAG 和 A3S hub 均已获授权，stdio 会列出 Vortex 上下文工具和 run_advanced_code_analysis。

Vortex 分析可用时：

需要将工作区挂载在 /app/mcp-workspace

• run_advanced_code_analysis - 对单个文件运行 Vortex 分析。在 Cloud 上，如果 SONARQUBE_ORG 未固定组织，请使用可选参数 organization；如果组织不明确，请使用 list_organizations。SonarQube Server 使用 nil UUID 占位符。
  • organization - Cloud 组织密钥；默认为已配置的组织或启动时唯一检测到的组织 - 可选 String
  • projectKey - 项目的密钥 - 必填 String （定义了 SONARQUBE_PROJECT_KEY 时将忽略）
  • branch - 用于获取最新分析上下文的分支名称 - 必填 String
  • filePath - 要分析文件的相对于项目的路径（例如 src/main/java/MyClass.java）。 - 必填 String
  • fileScope - 定义文件所属的范围：'MAIN' 或 'TEST'（默认值：MAIN） - String

覆盖率

• search_files_by_coverage - 按覆盖率升序（覆盖率最低的文件排在最前）搜索项目中的文件。此工具有助于识别需要提高测试覆盖率的文件。

  • projectKey - 要搜索的项目键 - 必填 String (定义了 SONARQUBE_PROJECT_KEY 时忽略)
  • branch - 可选的分支名称，用于按分支分析。使用 list_branches 查找有效名称 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String
  • maxCoverage - 覆盖率上限（0-100）。仅返回覆盖率 <= 此值的文件 - Number
  • pageIndex - 页码（从 1 开始，默认值：1） - Number
  • pageSize - 页面大小（默认值：100，最大值：500） - Number

• get_file_coverage_details - 获取特定文件逐行的覆盖率信息，包括哪些具体行未被覆盖，以及哪些行的分支仅被部分覆盖。此工具有助于精确定位需要添加测试覆盖的代码。通过 search_files_by_coverage 找到覆盖率较低的文件后使用。

  • key - 文件键（例如 my_project:src/foo/Bar.java） - 必填 String
  • branch - 可选的分支名称，用于按分支分析。使用 list_branches 查找有效名称 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String
  • from - 分析起始行（从 1 开始，默认值：1） - Number
  • to - 分析结束行（包含该行）。如果未指定，则返回所有行 - Number

依赖项风险

注意：仅在连接到 SonarQube Server 2025.4 Enterprise 或更高版本，且已启用 SonarQube Advanced Security 时，才能使用依赖项风险功能。

• search_dependency_risks - 搜索 SonarQube 项目的软件组成分析问题（依赖项风险），并关联分析项目、应用程序或项目组合中出现的版本。
  • projectKey - 项目键 - 必填 String (定义了 SONARQUBE_PROJECT_KEY 时忽略)
  • branch - 可选的分支名称，用于按分支分析。使用 list_branches 查找有效名称 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String
  • pageIndex - 可选的页码（从 1 开始，默认值：1） - Integer
  • pageSize - 可选的页面大小。必须大于 0 且小于或等于 500（默认值：100） - Integer

企业

注意：仅连接到 SonarQube Cloud 时，才能使用企业功能。

• list_enterprises - 列出你在 SonarQube Cloud 中有权访问的企业。使用此工具查找可用于其他工具的企业 ID。
  • enterpriseKey - 可选的企业键，用于筛选结果 - String

问题

• change_sonar_issue_status - 将 SonarQube 问题的状态更改为“accept”、“falsepositive”或“reopen”。

  • key - 问题键 - 必填字符串
  • status - 问题的新状态 - 必填枚举 {"accept", "falsepositive", "reopen"}
  • comment - 可选的评论，说明状态变更原因 - 字符串

• search_sonar_issues_in_projects - 搜索我所在组织的项目中的 SonarQube 问题。

  • projectKeys - 可选的 SonarQube 项目键列表 - 字符串[]
  • branch - 基于分支进行分析时使用的可选分支名称。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • severities - 可选的严重性筛选列表。可选值：INFO、LOW、MEDIUM、HIGH、BLOCKER - 字符串[]
  • impactSoftwareQualities - 可选的软件质量筛选列表。可选值：MAINTAINABILITY、RELIABILITY、SECURITY - 字符串[]
  • issueStatuses - 可选的问题状态筛选列表。可选值：OPEN、CONFIRMED、FALSE_POSITIVE、ACCEPTED、FIXED、IN_SANDBOX - 字符串[]
  • tags - 可选的问题标签筛选列表。标签均为小写 - 字符串[]
  • inNewCodePeriod - 仅返回新代码周期内的问题。projectKeys 和 files 中必须恰好有一项 - 布尔值
  • issueKey - 可选的问题键，用于获取特定问题 - 字符串
  • pageIndex - 可选的从 1 开始的页索引（默认值：1） - 整数
  • pageSize - 可选的分页大小。必须大于 0 且小于或等于 500（默认值：100） - 整数

安全热点

• search_security_hotspots - 搜索 SonarQube 项目中的安全热点。

  • projectKey - 项目或应用键 - 必填字符串 （定义 SONARQUBE_PROJECT_KEY 时会忽略）
  • hotspotKeys - 要获取的特定安全热点键，以逗号分隔 - 字符串[]
  • branch - 基于分支进行分析时使用的可选分支名称。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • files - 可选的文件路径筛选列表 - 字符串[]
  • status - 可选的状态筛选：TO_REVIEW、REVIEWED - 字符串
  • resolution - 可选的解决方式筛选：FIXED、SAFE、ACKNOWLEDGED - 字符串
  • sinceLeakPeriod - 筛选自代码泄漏周期（新代码）以来创建的热点 - 布尔值
  • onlyMine - 仅显示分配给我的热点 - 布尔值
  • pageIndex - 可选的从 1 开始的页索引（默认值：1） - 整数
  • pageSize - 可选的分页大小。必须大于 0 且小于或等于 500（默认值：100） - 整数

• show_security_hotspot - 获取特定安全热点的详细信息，包括规则详情、代码上下文、流和评论。

  • hotspotKey - 安全热点键 - 必填字符串

• change_security_hotspot_status - 通过更改状态来审查安全热点。标记为 REVIEWED 时，必须指定解决方式（FIXED、SAFE 或 ACKNOWLEDGED）。

  • hotspotKey - 安全热点键 - 必填字符串
  • status - 新状态 - 必填枚举 {"TO_REVIEW", "REVIEWED"}
  • resolution - 状态为 REVIEWED 时的解决方式 - 枚举 {"FIXED", "SAFE", "ACKNOWLEDGED"}
  • comment - 可选的审查评论 - 字符串

语言

• list_languages - 列出此 SonarQube 实例支持的所有编程语言。
  • q - 可选的模式，用于匹配语言键/名称 - 字符串

度量指标

• get_component_measures - 获取组件（项目、目录、文件）的 SonarQube 度量指标。
  • projectKey - 项目密钥 - 未配置 SONARQUBE_PROJECT_KEY 时必填，类型为 String
  • branch - 可选的分支名称，用于基于分支的分析。使用 list_branches 查找有效名称 - String
  • metricKeys - 可选的度量指标密钥，用于指定要获取的指标（例如 ncloc、complexity、violations、coverage）- String[]
  • pullRequest - 可选的拉取请求密钥/ID。使用 list_pull_requests 查找有效密钥 - String

指标

• search_metrics - 搜索 SonarQube 指标。
  • pageIndex - 可选的页码，从 1 开始（默认值：1）- Integer
  • pageSize - 可选的页面大小。必须大于 0 且小于或等于 500（默认值：100）- Integer

项目组合

• list_portfolios - 列出 SonarQube 中可用的企业项目组合，并提供筛选和分页选项。

  适用于 SonarQube Server：

  • q - 可选的搜索查询，用于按名称或密钥筛选项目组合 - String
  • favorite - 如果为 true，则仅返回收藏的项目组合 - Boolean
  • pageIndex - 可选的页码，从 1 开始（默认值：1）- Integer
  • pageSize - 可选的页面大小，最大为 500（默认值：100）- Integer

  适用于 SonarQube Cloud：

  • enterpriseId - 企业 UUID。仅当提供值为 true 的 'favorite' 参数时才可省略 - String
  • q - 可选的搜索查询，用于按名称筛选项目组合 - String
  • favorite - 省略 'enterpriseId' 参数时必须为 true。如果为 true，则仅返回当前登录用户收藏的项目组合。'draft' 为 true 时不能设为 true - Boolean
  • draft - 如果为 true，则仅返回当前登录用户创建的草稿。'favorite' 为 true 时不能设为 true - Boolean
  • pageIndex - 可选的要获取的页码（默认值：1）- Integer
  • pageSize - 可选的要获取的页面大小（默认值：50）- Integer

项目

• list_organizations - 列出用户所属的 SonarQube Cloud 组织，包括密钥、名称、ID 和 UUID。后续工具调用时，可将返回的密钥用作 organization。

• search_my_sonarqube_projects - 查找 SonarQube 项目。响应采用分页形式。

  • pageIndex - 可选的页码，从 1 开始（默认值：1）- Integer
  • pageSize - 可选的页面大小。必须大于 0 且小于或等于 500（默认值：500）- Integer
  • q - 可选的搜索查询，用于按名称（部分匹配）或密钥（完全匹配）筛选项目 - String

• list_branches - 列出项目中已分析的分支。

  • SonarQube Cloud：返回长期分支（LONG）和短期分支（SHORT），并包含 type 和 mergeBranch 字段。可选的 branchTypes 筛选项：ALL（默认值）、LONG 或 SHORT。
  • SonarQube Server：返回所有已分析的分支（名称、质量门禁、分析日期）。不提供 type、mergeBranch 或 branchTypes 筛选项。
  • 在其他工具中使用返回的分支名称作为 branch 参数。对于拉取请求分析，请改用 list_pull_requests。
  • projectKey - 项目密钥（例如 my_project）- 必填，类型为 String （定义了 SONARQUBE_PROJECT_KEY 时忽略）
  • branchTypes - （仅限 SonarQube Cloud） 可选的筛选项：ALL（默认值）、LONG 或 SHORT - Enum {"ALL", "LONG", "SHORT"}

• list_pull_requests - 列出项目的所有拉取请求。使用此工具查找用于 PR 装饰分析（覆盖率、问题、质量门禁）的拉取请求。返回的拉取请求密钥/ID 可用于其他工具。对于不涉及拉取请求的基于分支的分析，请改用 list_branches。

  • projectKey - 项目密钥（例如 my_project）- 必填，类型为 String （定义了 SONARQUBE_PROJECT_KEY 时忽略）

质量门禁

• get_project_quality_gate_status - 获取 SonarQube 项目的质量门禁状态。

  • analysisId - 可选的分析 ID - String
  • branch - 可选的分支名称，用于基于分支的分析。使用 list_branches 查找有效名称 - String
  • projectId - 可选的项目 ID - String
  • projectKey - 可选的项目键 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String

• list_quality_gates - 列出我的 SonarQube 中的所有质量门禁。

规则

• show_rule - 显示 SonarQube 规则的详细信息。
  • key - 规则键 - Required String

重复项

• search_duplicated_files - 搜索 SonarQube 项目中存在代码重复的文件。默认情况下，会自动获取所有页面中的重复文件（最多 10,000 个文件）。仅返回存在重复项的文件。

  • projectKey - 项目键 - Required String (定义了 SONARQUBE_PROJECT_KEY 时将忽略)
  • branch - 可选的分支名称，用于基于分支的分析。使用 list_branches 查找有效名称 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String
  • pageSize - 手动分页时每页的可选结果数（最大值：500）。未指定时，将自动获取所有重复文件 - Integer
  • pageIndex - 手动分页时的可选页码（从 1 开始）。未指定时，将自动获取所有重复文件 - Integer

• get_duplications - 获取文件中的重复项。需要拥有文件所属项目的 Browse 权限。

  • key - 文件键 - Required String
  • branch - 可选的分支名称，用于基于分支的分析。使用 list_branches 查找有效名称 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String

源码

• get_raw_source - 从 SonarQube 获取纯文本格式的源代码。需要拥有文件的“See Source Code”权限。

  • key - 文件键 - Required String
  • branch - 可选的分支名称，用于基于分支的分析。使用 list_branches 查找有效名称 - String
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - String

• get_scm_info - 获取 SonarQube 源文件的 SCM 信息。需要拥有文件所属项目的 See Source Code 权限。

  • key - 文件键 - Required String
  • commits_by_line - 如果值为 false，则按 SCM 提交对行分组；否则显示每行对应的提交 - String
  • from - 要返回的起始行号，从 1 开始 - Number
  • to - 要返回的结束行号（包含此行） - Number

系统

注意：仅连接到 SonarQube Server 时，才能使用系统工具。

• get_system_health - 获取 SonarQube Server 实例的运行状况。返回 GREEN（完全正常运行）、YELLOW（可用但需要关注）或 RED（未运行）。

• get_system_info - 获取 SonarQube Server 系统配置的详细信息，包括 JVM 状态、数据库、搜索索引和设置。需要“Administer”权限。

• get_system_logs - 以纯文本格式获取 SonarQube Server 系统日志。需要系统管理权限。

  • name - 要获取的日志的可选名称。可能的值：access、app、ce、deprecation、es、web。默认值：app - String

• ping_system - Ping SonarQube Server 系统以检查其是否正常运行。以纯文本格式返回“pong”。

• get_system_status - 获取 SonarQube Server 的状态信息。返回状态（STARTING、UP、DOWN、RESTARTING、DB_MIGRATION_NEEDED、DB_MIGRATION_RUNNING）、版本和 ID。

Webhooks

• create_webhook - 为 SonarQube 组织或项目创建新的 webhook。需要在指定项目上拥有“Administer”权限，或拥有全局“Administer”权限。

  • name - Webhook 名称 - 必填字符串
  • url - Webhook URL - 必填字符串
  • projectKey - 可选的项目键，用于创建项目专属 webhook - 字符串
  • secret - 可选的 webhook 密钥，用于保护 webhook 负载 - 字符串

• list_webhooks - 列出 SonarQube 组织或项目的所有 webhook。需要在指定项目上拥有“Administer”权限，或拥有全局“Administer”权限。

  • projectKey - 可选的项目键，用于列出项目专属 webhook - 字符串

上下文增强

• get_current_architecture - 获取按路径前缀和深度筛选的分层架构图。适用于探索模块结构和高层依赖关系。

  • depth - 层级深度（0 = 仅根节点，1 = 根节点 + 子节点，依此类推） - 必填整数
  • path_prefix - 用于筛选节点的可选路径前缀（例如，com.example.service） - 字符串
  • ecosystem - 用于筛选的可选生态系统（java、cs、py、js、ts） - 字符串

• get_intended_architecture - 获取用户定义的架构约束，指定哪些模块可以依赖其他模块。

# macOS/Linux (Bash/Zsh)
export SONARQUBE_TOKEN="{<YourUserToken>}"

{
  "mcpServers": {
    "sonarqube-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-e", "SONARQUBE_TOOLSETS",
        "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_ORG": "<YourOrganizationKey>",
        "SONARQUBE_PROJECT_KEY": "<YourProjectKey>",
        "SONARQUBE_TOOLSETS": "cag"
      }
    }
  }
}

Agentic Readiness

注意：Agentic Readiness 工具仅适用于 SonarQube Cloud，且需要为你的组织启用此功能。

• start_agentic_readiness_assessment - 为项目启动 Agentic Readiness 评估。立即返回状态 PENDING 和 assessmentId。使用 get_agentic_readiness_assessment 轮询结果。

  • projectKey - 项目键 - 必填字符串 (定义了 SONARQUBE_PROJECT_KEY 时会忽略)
  • branch - 要评估的分支。省略则使用项目的默认分支 - 字符串

• get_agentic_readiness_assessment - 获取评估结果。使用相同的 assessmentId 重复调用，直到状态为 COMPLETED、FAILED 或 INTERRUPTED。完成后，返回总体级别以及按支柱划分的结果，其中包含建议的操作和证据。

  • assessmentId - start_agentic_readiness_assessment 返回的评估 ID - 必填字符串

• list_agentic_readiness_assessments - 按时间从新到旧列出项目的所有评估。使用 get_agentic_readiness_assessment 获取完整的支柱级结果。

  • projectKey - 要列出评估的项目键 - 必填字符串 (定义了 SONARQUBE_PROJECT_KEY 时会忽略)
  • branch - 按分支名称筛选评估。省略则列出所有分支的评估 - 字符串
  • pageIndex - 从 1 开始的页索引（默认值：1）- 数字
  • pageSize - 每页条目数，最多 100（默认值：50）- 数字

架构

注意：将 architecture 添加到 SONARQUBE_TOOLSETS，即可在 stdio 或 HTTP 模式下启用这些工具。SonarQube Cloud 需要 Team 或 Enterprise 套餐。SonarQube Server 仅公开当前架构；在支持通过公开 API 解析项目 UUID 之前，预期架构的读取和写入仅适用于 Cloud。

• architecture_get - 读取当前依赖关系或预期分组和约束。当前视图最多显示 150 个节点；使用 component 或 language 缩小视图范围。未显示的同级节点可能仍无法发现，因此，受节点数限制的视图并非完整的图谱导出。

  每个工具实例最多可同时执行两次当前图谱读取。其他调用将等待最多五秒以获取执行名额，之后返回忙碌错误。每个已接受的调用仍会下载并处理所选的完整图谱。

  参数：

  • target - Cloud 上为 current 或 intended；Server 上为 current - 必需的枚举
  • projectKey - 项目键 - 必需的字符串 （如果已定义 SONARQUBE_PROJECT_KEY，则忽略）
  • organization - 未配置组织时使用的 SonarQube Cloud 组织键；读取 current 时必需 - 可选字符串
  • component - 精确匹配返回的当前节点键（Java：module:package）或预期分组键（标签以 / 连接）；不支持通配符；省略时从顶层开始 - 字符串
  • depth - 起始节点以下的层级数（默认值：current 为 1，intended 为全部）- 数字
  • language - java、cs、js、ts 或 py；省略时表示全部 - 字符串

• architecture_set - 在 Cloud 上替换整个预期模型。请从未经过滤的 architecture_get 响应开始，并使用 dryRun: true 查看更改。Server 上或 SONARQUBE_READ_ONLY=true 时不可用。OAuth 需要同时具有读取和写入范围。

  数据丢失限制： 未提供的视角和分组将被删除。如果导出的模型中包含视角标签、说明和导入的模式链接，则这些内容会保留。导入的模式仍为引用：公开导出不会展开其分组或约束，并且无法在此处编辑导入的内容。系统会拒绝部分视图和整体模型为空的情况。请提供完整响应以保留其修订版本检查；并发编辑仍可能与检查发生竞争。确定的 HTTP 客户端拒绝会直接转发。如果无法验证所需状态，写入结果不确定时会返回恢复用导出；不会尝试自动回滚。

  参数：

  • target - intended - 必需的枚举
  • projectKey - 项目键 - 必需的字符串 （如果已定义 SONARQUBE_PROJECT_KEY，则忽略）
  • organization - 未配置组织时使用的 SonarQube Cloud 组织键 - 可选字符串
  • model - 来自完整未过滤响应或其 models 数组的 JSON - 必需的字符串
  • dryRun - true 表示预览，false 表示应用 - 必需的布尔值
  • revision - 导出的修订版本；默认使用完整响应中的修订版本。不包含此值的裸数组无法检测导出后发生的更改 - 字符串

示例提示词

设置好 SonarQube MCP Server 后，以下是一些常见实际场景的示例提示词：

My quality gate is failing for my project. Can you help me understand why and fix the most critical issues?

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?

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?

We're deploying to production tomorrow. Can you check the quality gate status and alert me to any critical issues in this branch?

I want to reduce technical debt in my project. What are the top issues I should prioritize?

Our code coverage dropped below 70%. Can you identify which files have the lowest coverage and help me improve it?

I have 15 new code smells in my latest commit. Can you explain what they are and help me fix them?

SonarQube flagged a critical security vulnerability in <AuthController.java>. What's the issue and how do I fix it?

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?

Are there any known vulnerabilities in our dependencies? Check this project for dependency risks.

I just wrote this authentication function. Can you analyze it for security issues and code quality problems before I commit?

Review the changes in <src/database/migrations> for any potential bugs or security issues.

Give me a health report for my project: quality gate status, number of bugs, Security Hotspots, and code coverage.

Compare code quality between our main branch and the develop branch. Are we introducing new issues?

What are the most common rule violations across all our projects? We might need to update our coding standards.

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?

建议使用 sonarsource/sonarqube-mcp 容器镜像。

如需在不使用 Docker 的情况下将服务器作为独立 JAR 运行，请从 SonarSource 二进制文件仓库下载预构建版本。每个已发布版本都会以 sonarqube-mcp-server-<version>.jar 的形式发布在此处（例如，sonarqube-mcp-server-1.19.0.2785.jar）。

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-jar",
      "<path_to_sonarqube_mcp_server_jar>"
    ],
    "env": {
      "STORAGE_PATH": "<path_to_your_mcp_storage>",
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_ORG": "<org>"
    }
  }
}

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-jar",
      "<path_to_sonarqube_mcp_server_jar>"
    ],
    "env": {
      "STORAGE_PATH": "<path_to_your_mcp_storage>",
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

./gradlew clean build -x test

./gradlew :dependencies --write-locks
./gradlew :its:dependencies --write-locks

故障排除

默认情况下，应用程序日志会写入 STORAGE_PATH/logs/mcp.log 文件。如需完全禁用文件日志记录，请设置 SONARQUBE_LOG_TO_FILE_DISABLED=true。

常见问题

“不支持 SonarQube 服务器版本”

MCP 服务会在启动期间检查所连接的 SonarQube Server 版本。如果实例版本低于 2025.1（SQS）或 25.1（SQCB），启动将失败，并显示：

SonarQube server version is not supported, minimal version is SQS 2025.1 or SQCB 25.1

**解决方案：**将 SonarQube Server 升级到受支持的版本。此检查仅适用于连接 SonarQube Server 时（设置了 SONARQUBE_URL，但未设置 SONARQUBE_ORG），不适用于 SonarQube Cloud。

“功能无法使用”或“缺少工具/功能”

你可能正在运行过时的 Docker 镜像。Docker 会在本地缓存镜像，因此不会自动获取更新。

**解决方案：**更新到最新版本：

docker pull sonarsource/sonarqube-mcp

拉取最新镜像后，重启 MCP 客户端以使用更新后的版本。

你也可以在 docker run 命令中添加 --pull=always 标志，以便始终检查并拉取最新版本：

docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

“我想固定到特定版本”

在 sonarsource/sonarqube-mcp 查看可用标签，并引用所需版本：

docker pull sonarsource/sonarqube-mcp:1.19.0.2785

docker run --init -i --rm \
  -e SONARQUBE_TOKEN -e SONARQUBE_ORG \
  sonarsource/sonarqube-mcp:1.19.0.2785

在 MCP 客户端配置中，使用 sonarsource/sonarqube-mcp:<version> 替代 sonarsource/sonarqube-mcp，并移除 --pull=always，以防 Docker 在不提示的情况下升级镜像。

数据与遥测

此服务会收集匿名使用数据并发送给 SonarSource，以帮助改进产品。不会收集源代码或 IP 地址，SonarSource 也不会与他人共享这些数据。可通过以下系统属性或环境变量禁用遥测收集：TELEMETRY_DISABLED=true。点击此处查看所收集数据的示例。

许可证

版权所有 2025 SonarSource。

依据 SONAR Source-Available License v1.0 许可。按照本文档使用 SonarQube MCP Server 属于非竞争用途，因此符合 SSAL 的许可规定。

你通过 MCP 使用 SonarQube 时，须遵守 SonarQube Cloud 服务条款或 SonarQube Server 条款与条件，包括仅将结果数据用于内部软件开发目的。