Metadata-Version: 2.4
Name: sonarqube-mcp
Version: 0.1.0
Summary: MCP server for SonarQube — projects, metrics, quality gate, issues, worst-metric ranking.
Project-URL: Homepage, https://github.com/mshegolev/sonarqube-mcp
Project-URL: Issues, https://github.com/mshegolev/sonarqube-mcp/issues
Author: Mikhail Shchegolev
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,code-quality,mcp,sonarcloud,sonarqube,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Requires-Dist: typing-extensions>=4.5; python_version < '3.12'
Requires-Dist: urllib3>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# sonarqube-mcp

<!-- mcp-name: io.github.mshegolev/sonarqube-mcp -->

[![PyPI](https://img.shields.io/pypi/v/sonarqube-mcp.svg?logo=pypi&logoColor=white)](https://pypi.org/project/sonarqube-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/sonarqube-mcp.svg?logo=python&logoColor=white)](https://pypi.org/project/sonarqube-mcp/)
[![License: MIT](https://img.shields.io/pypi/l/sonarqube-mcp.svg)](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.

## Development

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

## License

MIT © Mikhail Shchegolev
