Content
# MCP SonarQube Server
[](https://dotnet.microsoft.com/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](#available-tools)
[](#development)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants talk to SonarQube — query projects, drill into issues, audit pull requests, locate duplication, and check quality gates — all through a single HTTP transport.
### Highlights
- **PR analysis in one call** — `analyze_pull_request` aggregates quality gate, new-code measures, issues, and security hotspots in parallel
- **Locate the offending file** — `get_component_tree_measures` breaks aggregated metrics down by file/directory so the agent knows where to fix
- **Exact duplication blocks** — `get_duplications` returns line ranges and paired files
- **Clear errors** — Sonar's error body (`errors[].msg`) is propagated through every wrapper
---
## Quick Start
```bash
# 1. Clone the repository
git clone https://github.com/viamus/mcp-sonarqube.git
cd mcp-sonarqube
# 2. Configure credentials
cp .env.example .env
# Edit .env with your SonarQube URL and token
# 3. Run the server
docker compose up -d
```
---
## Prerequisites
| Requirement | Version | Purpose |
|-------------|---------|---------|
| .NET SDK | 10.0+ | Build and run |
| Docker | Latest | Container deployment (optional) |
| SonarQube Instance | 9.x+ | API access |
**Required:**
- SonarQube base URL (e.g., `https://sonarqube.example.com`)
- SonarQube user token (generate at: Your SonarQube > My Account > Security > Tokens)
---
## Available Tools
13 MCP tools, grouped by domain:
| Domain | Tool | Purpose |
|--------|------|---------|
| **Pull Requests** | `analyze_pull_request` | Aggregated PR view — quality gate, new-code measures, issues, security hotspots (4 calls in parallel) |
| **Projects** | `search_projects` | Search projects by name or key |
| | `get_project_status` | Quality gate status + key measures for a project |
| **Issues** | `search_issues` | Search issues with filters; supports `pullRequest` scoping |
| **Measures** | `get_measures` | Get metrics for a component |
| | `get_component_tree_measures` | Break measures down by file/directory — locate offending files |
| **Duplications** | `get_duplications` | Exact duplication blocks (line ranges + paired files) |
| **Quality Gates** | `list_quality_gates` | List all gates with their conditions |
| **Hotspots** | `search_hotspots` | Search security hotspots |
| | `get_hotspot` | Detailed hotspot info |
| **Rules** | `search_rules` | Search coding rules by language/severity/tags |
| **System** | `get_health` | Health status of the SonarQube instance |
For the underlying SonarQube endpoints each tool wraps, see the [API Reference](#api-reference) below.
---
## Running Options
### Option 1: Docker Compose (Recommended)
```bash
docker compose up -d
```
The server will be available at `http://localhost:8082`.
### Option 2: .NET CLI
```bash
dotnet run --project src/Viamus.Sonarqube.Mcp.Server
```
The server will be available at `http://localhost:5100`.
### Option 3: Self-Contained Executable
```bash
dotnet publish src/Viamus.Sonarqube.Mcp.Server -c Release -o ./publish
./publish/Viamus.Sonarqube.Mcp.Server
```
---
## Client Configuration
### Claude Desktop
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"sonarqube": {
"url": "http://localhost:8082"
}
}
}
```
### Claude Code
```bash
claude mcp add sonarqube --scope user --transport http http://localhost:8082
```
---
## Usage Examples
### Audit a pull request end-to-end
```
Analyze pull request 1234 on the "my-app" project. Did it break the gate?
If yes, find which files concentrate the new duplicated lines and show me
the exact duplication blocks.
```
> Under the hood the agent will typically chain `analyze_pull_request` → `get_component_tree_measures` (sorted by `new_duplicated_lines`) → `get_duplications` on the worst file.
### Search for projects
```
Search for all projects containing "backend" in my SonarQube instance.
```
### Check project quality
```
What is the quality gate status for the "my-app" project? Show me the coverage and bug count.
```
### Find critical issues
```
Search for all CRITICAL and BLOCKER severity issues in the "my-app" project.
```
### Review security hotspots
```
Show me all security hotspots that need review in the "my-app" project.
```
### Search coding rules
```
Find all MAJOR severity rules for C# language.
```
### Check system health
```
Is my SonarQube instance healthy?
```
---
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SONARQUBE_BASE_URL` | Yes | SonarQube instance URL |
| `SONARQUBE_TOKEN` | Yes | SonarQube user token |
| `SONARQUBE_ORGANIZATION` | No | SonarCloud organization key |
| `SERVER_REQUIRE_API_KEY` | No | Enable API key authentication (default: `false`) |
| `SERVER_API_KEY` | No | API key for server access |
### appsettings.json
```json
{
"SonarQube": {
"BaseUrl": "https://your-sonarqube-instance.com",
"Token": "your-token-here",
"Organization": ""
},
"ServerSecurity": {
"RequireApiKey": false,
"ApiKey": ""
}
}
```
### User Secrets (Development)
```bash
cd src/Viamus.Sonarqube.Mcp.Server
dotnet user-secrets set "SonarQube:BaseUrl" "https://your-sonarqube-instance.com"
dotnet user-secrets set "SonarQube:Token" "your-token-here"
dotnet user-secrets set "SonarQube:Organization" "your-sonarcloud-organization"
```
---
## Troubleshooting
### Common Issues
**Connection refused**
- Verify the SonarQube base URL is correct and accessible
- Check that the server is running: `curl http://localhost:8082/health`
**401 Unauthorized from SonarQube**
- Verify your token is valid and not expired
- Generate a new token at: Your SonarQube > My Account > Security > Tokens
**No projects found**
- Ensure your token has sufficient permissions
- Verify the project exists in your SonarQube instance
**Docker container not starting**
- Check logs: `docker compose logs mcp-sonarqube`
- Verify `.env` file exists and contains valid credentials
---
## Project Structure
```
mcp-sonarqube/
├── src/Viamus.Sonarqube.Mcp.Server/
│ ├── Configuration/ # Settings classes
│ ├── Middleware/ # API key authentication
│ ├── Models/ # SonarQube API DTOs
│ ├── Services/ # HTTP client for SonarQube API
│ ├── Tools/ # MCP tool implementations (13 tools)
│ └── Program.cs # Entry point
├── tests/Viamus.Sonarqube.Mcp.Server.Tests/
│ ├── Configuration/ # Settings and middleware tests
│ ├── Models/ # Serialization tests
│ └── Tools/ # Tool behavior tests
├── docker-compose.yml
└── Solution.slnx
```
---
## API Reference
### SonarQube API Endpoints Used
| Endpoint | Tool(s) |
|----------|---------|
| `/api/projects/search` | `search_projects` |
| `/api/qualitygates/project_status` | `get_project_status`, `analyze_pull_request` |
| `/api/qualitygates/list` | `list_quality_gates` |
| `/api/measures/component` | `get_project_status`, `get_measures`, `analyze_pull_request` |
| `/api/measures/component_tree` | `get_component_tree_measures` |
| `/api/duplications/show` | `get_duplications` |
| `/api/issues/search` | `search_issues`, `analyze_pull_request` |
| `/api/hotspots/search` | `search_hotspots`, `analyze_pull_request` |
| `/api/hotspots/show` | `get_hotspot` |
| `/api/rules/search` | `search_rules` |
| `/api/system/health` | `get_health` |
---
## Development
### Building
```bash
dotnet build Solution.slnx
```
### Testing
```bash
dotnet test Solution.slnx
```
### Adding New Tools
See [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-new-mcp-tool) for detailed instructions.
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
rea
Reverse engineering for coding agents: one CLI and MCP server to inspect any...
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
cc-switch
All-in-One Assistant for Claude Code, Codex & Gemini CLI across platforms.
Agent-Reach
Give your AI agent eyes to see the entire internet. Read & search Twitter,...
servers
Model Context Protocol Servers