io.github.mshegolev/sonarqube-mcp
SonarQube MCP — projects, metrics, quality gate, issues, worst-metric ranking.
Open source Open in the app JSON README (API)
About
SonarQube MCP — projects, metrics, quality gate, issues, worst-metric ranking.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- mshegolev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Open pull requests
- 1
- Last push
- 2026-08-12T15:34:25Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:51
- Updated
- 2026-08-29 04:00:51
- Origin id
io.github.mshegolev/sonarqube-mcp
README
# sonarqube-mcp
<!-- mcp-name: io.github.mshegolev/sonarqube-mcp -->
[](https://pypi.org/project/sonarqube-mcp/)
[](https://pypi.org/project/sonarqube-mcp/)
[](LICENSE)
MCP server for [SonarQube](https://www.sonarsource.com/products/sonarqube/). Lets an LLM agent (Claude Code, Cursor, OpenCode, etc.) discover projects, pull headline metrics, check Quality Gate status, search issues with severity/type filters, and rank projects by the *worst* value of any metric.
Python, [FastMCP](https://github.com/modelcontextprotocol/python-sdk), stdio transport.
Works with any SonarQube 9.x / 10.x instance (self-hosted) and with SonarCloud.
## Why another SonarQube MCP?
A few community SonarQube MCPs exist, but they tend to stop at single-project reads. This one adds **cross-project ranking** (`sonarqube_worst_metrics`) — the operation a lead actually runs during a triage session: "show me the top 10 worst-coverage services in the org". All tools are read-only and safely parameterised (Pydantic input validation, severity / type whitelists).
## Design highlights
- **Tool annotations** — all five tools carry `readOnlyHint: True`, `destructiveHint: False`, `idempotentHint: True`. Nothing can mutate SonarQube from this server.
- **Structured output** — every tool returns a typed payload (TypedDict) + a markdown summary, so clients with and without structured-content support both get a usable response.
- **Structured errors** — 401 / 403 / 404 / 400 / 429 / 5xx mapped to actionable hints (e.g. "regenerate token", "check project key with sonarqube_list_projects").
- **Pydantic input validation** for every argument; severity / type filters are checked against the valid SonarQube enum before the request is sent.
- **Cross-project worst-metric ranking** — batches `/api/measures/search` calls under the hood, sorts ascending or descending based on whether higher is worse for the chosen metric.
## Features (5 tools)
**Discovery**
- `sonarqube_list_projects` — paginated project search with optional text filter
**Single-project insight**
- `sonarqube_project_metrics` — measures for one project (default set covers bugs / coverage / smells / ratings / ncloc / tests / alert_status)
- `sonarqube_quality_gate_status` — Quality Gate status + per-condition failures
**Issue triage**
- `sonarqube_get_issues` — issue search filtered by severity / type / resolution status
**Cross-project ranking**
- `sonarqube_worst_metrics` — top-N projects sorted by the worst value of a metric (e.g. worst coverage, most bugs)
## Installation
Requires Python 3.10+.
```bash
# via uvx (recommended — no install, just run)
uvx --from sonarqube-mcp sonarqube-mcp
# or via pipx
pipx install sonarqube-mcp
```
## Configuration
```bash
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
```
Or in `.mcp.json`:
```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"
}
}
}
}
```
Check:
```bash
claude mcp list
# sonarqube: uvx --from sonarqube-mcp sonarqube-mcp - ✓ Connected
```
## Environment variables
| Variable | Required | Description |
|---|---|---|
| `SONARQUBE_URL` | yes | SonarQube URL (no trailing slash) |
| `SONARQUBE_TOKEN` | yes | Bearer token. Generate in: My Account → Security → Tokens |
| `SONARQUBE_SSL_VERIFY` | no | `true`/`false`. Default: `true`. |
**Note on HTTP proxies.** The client intentionally disables env-based proxy discovery (`trust_env=False`) because self-hosted SonarQube is typically reachable only on an internal network. If you connect to SonarCloud or any SonarQube that lives *behind* a corporate proxy, you'll currently need to drop the proxy variables at the process level — a `SONARQUBE_TRUST_ENV_PROXY` knob is planned for a follow-up release.
## Example usage
- "List all SonarQube projects matching 'einvy'"
- "What's the Quality Gate status for `einvy:aut_einvy`?"
- "Show me the top 10 projects with the most bugs"
- "Find all BLOCKER / CRITICAL vulnerabilities in `einvy:aut_einvy`"
- "What's the coverage on `einvy:qa_assistant`?"
- "Top 5 worst-coverage projects matching query 'einvy'"
## Metric directions (used by `sonarqube_worst_metrics`)
**Higher is worse** (sorted descending — more is worse):
`bugs`, `code_smells`, `vulnerabilities`, `duplicated_lines_density`, `reliability_rating`, `security_rating`, `security_review_rating`, `sqale_rating`, `open_issues`
**Lower is worse** (sorted ascending — less is worse):
`coverage`, `line_coverage`, `branch_coverage`, `test_success_density`, `tests`
Ratings in SonarQube are numeric strings `"1"` (A, best) through `"5"` (E, worst).
## Safety
- All tools are `readOnlyHint: True` — nothing can mutate SonarQube.
- No `POST` / `PUT` / `DELETE` is ever called.
- Severity / type / qualifier inputs are validated against SonarQube enums before the API call, so the tool fails fast on typos rather than hitting the API.
## Performance characteristics
- Every tool makes **one HTTP call** to SonarQube except `sonarqube_worst_metrics`, which makes **one search call + ⌈candidate_pool/100⌉ bulk-measures calls**. Default settings land at ≤ 2 calls.
- Single-tool response time on a healthy SonarQube instance: typically < 500 ms.
- Pagination is passed through to SonarQube (`p` + `ps` params) — no full-result buffering in the MCP server.
- `sonarqube_worst_metrics` caps `candidate_pool` at 500 — on instances with thousands of projects, pre-filter with `query=` before ranking (see the tool docstring).
- SonarQube has no published hard rate limit. If 429 is received the server surfaces an actionable error ("Wait 30-60 s before retrying; reduce page_size").
## Development
```bash
git clone https://github.com/mshegolev/sonarqube-mcp.git
cd sonarqube-mcp
pip install -e '.[dev]'
pytest
```
## License
MIT © Mikhail Shchegolev