# SonarQube MCP Server

A read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants structured access to SonarQube — issues, metrics, rules, and projects.

## Features

- **6 read-only tools** covering the full SonarQube quality workflow
- **Safe by design** — no mutations, every tool returns a consistent `{"ok": ...}` envelope
- **Input validation** before any API call (severities, types, statuses)
- **Structured errors** with machine-readable `error_code` fields
- Works with SonarQube Community, Developer, and Enterprise editions

---

## Requirements

- Python 3.10+
- A running SonarQube instance
- A SonarQube user token (`squ_...`)

---

## Installation

```bash
pip install sonarqube-mcp-server
```

Or install from source:

```bash
git clone <repo>
cd sonarqube-mcp
pip install -e .
```

---

## Quick Start

```bash
SONARQUBE_URL=http://localhost:9000 \
SONARQUBE_TOKEN=squ_xxxxxxxxxxxx \
sonarqube-mcp-server
```

Or with `python -m`:

```bash
python -m sonarqube_mcp
```

---

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `SONARQUBE_URL` | No | `http://localhost:9000` | Base URL of your SonarQube instance |
| `SONARQUBE_TOKEN` | Yes | — | User token for authentication |
| `SONARQUBE_REQUEST_TIMEOUT_SEC` | No | `30` | HTTP request timeout in seconds |

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

### Generating a Token

In SonarQube: **My Account → Security → Generate Tokens**. A user token (`squ_...`) with Browse permission on the target projects is sufficient for all read-only operations.

---

## MCP Client Integration

### Claude Code

Add to your Claude Code MCP settings (`~/.claude/claude_code_config.json`):

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "sonarqube-mcp-server",
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_xxxxxxxxxxxx"
      }
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "sonarqube-mcp-server",
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "squ_xxxxxxxxxxxx"
      }
    }
  }
}
```

---

## Tools

All tools are **read-only** (`readOnlyHint: true`, `destructiveHint: false`).

### `check_status`

Verify connectivity and retrieve server version.

```json
{}
```

**Response:**
```json
{
  "ok": true,
  "server_url": "http://localhost:9000",
  "status": "UP",
  "version": "10.4.1"
}
```

---

### `list_projects`

List or search SonarQube projects with pagination.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `query` | `string` | — | Filter by project name or key |
| `page` | `integer` | `1` | Page number (1-indexed) |
| `page_size` | `integer` | `20` | Results per page (1–500) |

**Response:**
```json
{
  "ok": true,
  "total": 42,
  "page": 1,
  "page_size": 20,
  "projects": [
    {"key": "my-app", "name": "My Application", "qualifier": "TRK"}
  ]
}
```

---

### `search_issues`

Search issues across all projects or scoped to one project, with rich filtering.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `project_key` | `string` | — | Scope to a specific project |
| `severities` | `string` | — | CSV: `INFO`, `MINOR`, `MAJOR`, `CRITICAL`, `BLOCKER` |
| `types` | `string` | — | CSV: `CODE_SMELL`, `BUG`, `VULNERABILITY`, `SECURITY_HOTSPOT` |
| `statuses` | `string` | — | CSV: `OPEN`, `CONFIRMED`, `REOPENED`, `RESOLVED`, `CLOSED` |
| `tags` | `string` | — | CSV of tag names |
| `assigned` | `boolean` | — | `true` = assigned only, `false` = unassigned only |
| `page` | `integer` | `1` | Page number |
| `page_size` | `integer` | `20` | Results per page (1–500) |

**Example — find all open blockers in a project:**
```json
{
  "project_key": "my-app",
  "severities": "BLOCKER,CRITICAL",
  "statuses": "OPEN"
}
```

---

### `get_issue`

Get full detail for a single issue by key, including text range, effort, assignee, comments, and data-flow information.

| Parameter | Type | Description |
|---|---|---|
| `issue_key` | `string` | Issue key (e.g. `AXy1k2m3n4o5p6q7r8`) |

---

### `get_project_metrics`

Retrieve the quality dashboard for a project. Returns a standard set of metrics by default, or a custom selection.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `project_key` | `string` | — | **Required.** Project key |
| `metric_keys` | `string` | *See below* | CSV of metric keys |

**Default metrics:** `bugs`, `vulnerabilities`, `code_smells`, `security_hotspots`, `coverage`, `duplicated_lines_density`, `ncloc`, `sqale_index`, `reliability_rating`, `security_rating`, `sqale_rating`, `alert_status`, `quality_gate_details`

**Response:**
```json
{
  "ok": true,
  "project_key": "my-app",
  "project_name": "My Application",
  "metrics": {
    "bugs": "3",
    "coverage": "78.4",
    "alert_status": "OK"
  }
}
```

---

### `get_rule`

Retrieve the description and metadata for a SonarQube rule.

| Parameter | Type | Description |
|---|---|---|
| `rule_key` | `string` | Rule key (e.g. `python:S1192`, `java:S106`) |

---

## Error Handling

All tools return a consistent envelope. On failure:

```json
{
  "ok": false,
  "error_code": "auth_error",
  "message": "Authentication failed. Check SONARQUBE_TOKEN.",
  "details": {}
}
```

| `error_code` | Cause |
|---|---|
| `auth_error` | Invalid or missing token (HTTP 401) |
| `forbidden` | Token lacks permissions (HTTP 403) |
| `not_found` | Project, issue, or rule does not exist (HTTP 404) |
| `connection_error` | Cannot reach the SonarQube instance |
| `timeout` | Request exceeded `SONARQUBE_REQUEST_TIMEOUT_SEC` |
| `invalid_input` | Bad parameter value (e.g. unknown severity) |
| `api_error` | Other non-2xx SonarQube response |
| `internal_error` | Unexpected server-side error |

---

## Development

### Setup

```bash
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Project Layout

```
src/sonarqube_mcp/
├── server.py             # FastMCP server, tool definitions, main()
├── sonarqube_client.py   # httpx.Client wrapper for SonarQube REST API
├── settings.py           # Frozen dataclass + env var loading
├── errors.py             # SonarQubeError + error_response()
├── __main__.py           # python -m sonarqube_mcp entrypoint
└── __init__.py

tests/
├── conftest.py
├── test_server.py
├── test_client.py
├── test_settings.py
└── test_errors.py
```

### Architecture Notes

- `create_server()` is a factory that captures `settings` and `client` in closure scope — makes unit testing straightforward by injecting a pre-built `SonarQubeSettings`.
- `@_safe_tool` wraps every tool so it never raises — exceptions are caught and returned as structured error envelopes.
- `_clamp()` keeps `page_size` within SonarQube's supported API limits (1–500).
- Settings use a `frozen=True` dataclass — immutable after load, safe to share across tool closures.

---

## License

MIT