sonarqube-mcp

sonarqube-mcp

适用于 SonarQube 的 MCP 服务。可让大模型 Agent（Claude Code、Cursor、OpenCode 等）发现项目、获取关键指标、检查质量门状态、按严重程度／类型筛选问题，并根据任意指标的最差值为项目排名。

Python、FastMCP、stdio 传输。

适用于任何 SonarQube 9.x／10.x 实例（可自托管），也适用于 SonarCloud。

为什么还要做一个 SonarQube MCP？

目前已有一些社区版 SonarQube MCP，但通常仅支持读取单个项目的数据。这个 MCP 服务新增了跨项目排名（sonarqube_worst_metrics）——这正是负责人在问题分类会话中会执行的操作：“列出组织中覆盖率最差的 10 个服务”。所有工具均为只读，并经过安全的参数验证（Pydantic 输入验证、严重程度／类型白名单）。

设计亮点

• 工具注解 — 五个工具均带有 readOnlyHint: True、destructiveHint: False、idempotentHint: True。此服务无法修改 SonarQube 中的任何内容。
• 结构化输出 — 每个工具都会返回类型化载荷（TypedDict）和 Markdown 摘要，因此无论客户端是否支持结构化内容，都能获得可用的响应。
• 结构化错误 — 将 401／403／404／400／429／5xx 映射为可操作的提示（例如“重新生成令牌”“使用 sonarqube_list_projects 检查项目密钥”）。
• 每个参数都经过 Pydantic 输入验证；发送请求前，会根据有效的 SonarQube 枚举值检查严重程度／类型筛选条件。
• 跨项目最差指标排名 — 在底层批量调用 /api/measures/search，并根据所选指标值越高是否越差，按升序或降序排列。

功能（5 个工具）

发现

• sonarqube_list_projects — 分页搜索项目，可选文本筛选

单项目洞察

• sonarqube_project_metrics — 单个项目的指标（默认涵盖 bugs／coverage／smells／ratings／ncloc／tests／alert_status）
• sonarqube_quality_gate_status — 质量门状态及各条件的失败情况

问题分类

• sonarqube_get_issues — 按严重程度／类型／解决状态筛选问题

跨项目排名

• sonarqube_worst_metrics — 按某项指标的最差值对前 N 个项目排序（例如覆盖率最差、bug 数量最多）

安装

需要 Python 3.10+。

# via uvx (recommended — no install, just run)
uvx --from sonarqube-mcp sonarqube-mcp

# or via pipx
pipx install sonarqube-mcp

配置

claude mcp add sonarqube -s project \
  --env SONARQUBE_URL=https://sonar.example.com \
  --env SONARQUBE_TOKEN=squ_your_token \
  --env SONARQUBE_SSL_VERIFY=true \
  -- uvx --from sonarqube-mcp sonarqube-mcp

或者在 .mcp.json 中配置：

{
  "mcpServers": {
    "sonarqube": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "sonarqube-mcp", "sonarqube-mcp"],
      "env": {
        "SONARQUBE_URL": "https://sonar.example.com",
        "SONARQUBE_TOKEN": "${SONARQUBE_TOKEN}",
        "SONARQUBE_SSL_VERIFY": "true"
      }
    }
  }
}

检查：

claude mcp list
# sonarqube: uvx --from sonarqube-mcp sonarqube-mcp - ✓ Connected

环境变量

变量	必需	描述
SONARQUBE_URL	是	SonarQube URL（末尾不要带斜杠）
SONARQUBE_TOKEN	是	Bearer 令牌。生成路径：My Account → Security → Tokens
SONARQUBE_SSL_VERIFY	否	true／false。默认值：true。

关于 HTTP 代理的说明。 客户端会刻意禁用基于环境变量的代理发现（trust_env=False），因为可自托管的 SonarQube 通常只能通过内部网络访问。如果连接 SonarCloud 或位于企业代理之后的 SonarQube，目前需要在进程级别移除代理变量——后续版本计划提供 SONARQUBE_TRUST_ENV_PROXY 开关。

使用示例

• “列出所有与 ‘einvy’ 匹配的 SonarQube 项目”
• “einvy:aut_einvy 的质量门状态是什么？”
• “列出 bug 数量最多的前 10 个项目”
• “查找 einvy:aut_einvy 中所有 BLOCKER／CRITICAL 漏洞”
• “einvy:qa_assistant 的覆盖率是多少？”
• “列出与查询 ‘einvy’ 匹配的覆盖率最差的前 5 个项目”

指标方向（由 sonarqube_worst_metrics 使用）

数值越高越差（按降序排列——数值越大越差）： bugs、code_smells、vulnerabilities、duplicated_lines_density、reliability_rating、security_rating、security_review_rating、sqale_rating、open_issues

数值越低越差（按升序排列——数值越小越差）： coverage、line_coverage、branch_coverage、test_success_density、tests

SonarQube 中的评级为数字字符串，从 "1"（A，最佳）到 "5"（E，最差）。

安全性

• 所有工具的 readOnlyHint: True，不会对 SonarQube 进行任何修改。
• 绝不会调用 POST / PUT / DELETE。
• 在发起 API 调用前，会根据 SonarQube 枚举值验证严重性、类型和限定符输入，因此遇到拼写错误时工具会立即报错，而不会调用 API。

性能特征

• 除 sonarqube_worst_metrics 外，每个工具都会向 SonarQube 发起一次 HTTP 调用；sonarqube_worst_metrics 则会发起一次搜索调用 + ⌈候选池/100⌉ 次批量指标调用。使用默认设置时，调用次数不超过 2 次。
• 在运行正常的 SonarQube 实例上，单个工具的响应时间通常小于 500 ms。
• 分页参数会直接传递给 SonarQube（p + ps 参数）——MCP 服务不会缓冲完整结果。
• sonarqube_worst_metrics 将 candidate_pool 上限设为 500；在拥有数千个项目的实例上进行排名前，请使用 query= 预筛选（参见工具文档字符串）。
• SonarQube 未公布硬性速率限制。如果收到 429，服务会显示可执行的错误提示（“请等待 30-60 s 后重试；减小 page_size”）。

开发

git clone https://github.com/mshegolev/sonarqube-mcp.git
cd sonarqube-mcp
pip install -e '.[dev]'
pytest

许可证

MIT © Mikhail Shchegolev