SonarQube MCP Server

MCP (Model Context Protocol) server that exposes the SonarQube/SonarCloud API as tools for AI agents. It allows models like GitHub Copilot or Claude to query and manage projects, issues, hotspots, metrics, and more directly from the chat interface.

Table of contents

• Architecture
• Requirements
• Configuration
  • Authentication by SonarQube version
• Usage
  • VS Code integration (GitHub Copilot)
  • Claude Desktop integration
• Local development
• Available tools
  • System
  • Projects
  • Issues
  • Security hotspots
  • Measures and metrics
  • Quality Gates
  • Components
  • Source code
  • Rules
  • Duplications
  • Languages
  • Quality Profiles
• Project structure
• Tests

Architecture

The server follows a clean layered architecture:

┌─────────────────────────────────────┐
│            MCP Client               │
│  (Copilot / Claude / any LLM)       │
└──────────────┬──────────────────────┘
               │ stdio (JSON-RPC)
┌──────────────▼──────────────────────┐
│         Infrastructure              │
│  ┌─────────────────────────────┐    │
│  │  MCP Server (index.ts)      │    │
│  │  toolList · toolRouter      │    │
│  │  Domain handlers            │    │
│  └────────────┬────────────────┘    │
│  ┌────────────▼────────────────┐    │
│  │  Controllers (REST adapter) │    │
│  └────────────┬────────────────┘    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│           Application               │
│  Use Cases (one per operation)      │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│             Domain                  │
│  Interfaces · Types · Errors        │
└──────────────┬──────────────────────┘
               │ fetch (HTTP/HTTPS)
┌──────────────▼──────────────────────┐
│     SonarQube / SonarCloud API      │
└─────────────────────────────────────┘

Tool call flow:

1. The agent invokes a tool (e.g. issues).
2. The MCP Server receives the request via stdio and routes it with toolRouter.
3. The matching handler delegates to the application Use Case.
4. The Use Case calls the Controller, which extends SonarQubeApiBaseController.
5. The Controller makes the HTTP request to the SonarQube API and returns the result.
6. The response is serialized to JSON and returned to the agent.

Requirements

• Node.js ≥ 18
• A SonarQube instance (≥ 9.x) or a SonarCloud account
• Authentication credentials (see the section below)

No installation required — the package is consumed directly via npx.

Configuration

Authentication and the server URL are configured via environment variables:

| Environment variable | Description | | ------------------------ | ----------------------------------------------------------------- | | SONARQUBE_URL | Base URL of the instance (defaults to https://sonarcloud.io) | | SONARQUBE_TOKEN | User or service token | | SONARQUBE_USERNAME | Username for Basic auth | | SONARQUBE_PASSWORD | Password for Basic auth (can be empty when using a token as user) | | SONARQUBE_PASSCODE | System passcode (X-Sonar-Passcode header) | | SONARQUBE_ORGANIZATION | Organization key (required for SonarCloud) |

Authentication by SonarQube version

The authentication method depends on your SonarQube version:

SonarQube < 10 — Basic authentication

Set SONARQUBE_USERNAME and SONARQUBE_PASSWORD. There are two common patterns:

Using regular credentials:

SONARQUBE_URL=https://sonar.mycompany.com
SONARQUBE_USERNAME=my-user
SONARQUBE_PASSWORD=my-password

Using a token as the username (password left empty):

SONARQUBE_URL=https://sonar.mycompany.com
SONARQUBE_USERNAME=squ_xxxxxxxxxxxxxxxxxxxx
SONARQUBE_PASSWORD=

SonarQube ≥ 10 / SonarCloud — Token authentication

Set SONARQUBE_TOKEN with a user token or a service account token:

SONARQUBE_URL=https://sonar.mycompany.com
SONARQUBE_TOKEN=squ_xxxxxxxxxxxxxxxxxxxx
# SONARQUBE_ORGANIZATION=my-org  # required for SonarCloud only

Usage

The server communicates exclusively over stdio using the MCP JSON-RPC protocol. It does not expose any HTTP port.

VS Code integration (GitHub Copilot)

Add the following entry to your VS Code MCP configuration file (.vscode/mcp.json or the global mcp.json in your user settings folder):

SonarQube ≥ 10 / SonarCloud (token auth):

{
  "servers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-server-mcp@latest"],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_TOKEN": "squ_xxxxxxxxxxxxxxxxxxxx",
        "SONARQUBE_ORGANIZATION": "my-org"
      }
    }
  }
}

SonarQube < 10 (Basic auth with token as username):

{
  "servers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-server-mcp@latest"],
      "env": {
        "SONARQUBE_URL": "https://sonar.mycompany.com",
        "SONARQUBE_USERNAME": "squ_xxxxxxxxxxxxxxxxxxxx",
        "SONARQUBE_PASSWORD": ""
      }
    }
  }
}

Claude Desktop integration

In claude_desktop_config.json:

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-server-mcp@latest"],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_TOKEN": "squ_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Available tools

System

| Tool | Description | Required params | | --------------- | --------------------------------------------------------- | --------------- | | system_ping | Checks that SonarQube is available. Returns pong. | — | | system_health | Gets the server health status (GREEN, YELLOW, RED). | — | | system_status | Gets the system status with version information. | — |

Projects

| Tool | Description | Optional params | | ---------- | ---------------------------------------------------------- | ------------------ | | projects | Lists all available projects in SonarQube with pagination. | page, pageSize |

Issues

| Tool | Description | Required params | | ---------------------------- | --------------------------------------------------------------- | ------------------ | | issues | Searches and lists issues with multiple filters. | — | | issue_add_comment | Adds a comment to an issue. | issueKey, text | | issue_assign | Assigns an issue to a user (empty to unassign). | issueKey | | issue_confirm | Confirms an issue (CONFIRM transition). | issueKey | | issue_unconfirm | Unconfirms an issue (UNCONFIRM transition). | issueKey | | issue_mark_false_positive | Marks a single issue as a false positive. | issueKey | | issues_mark_false_positive | Marks multiple issues as false positives in a single operation. | issueKeys | | issue_mark_wont_fix | Marks a single issue as Won't Fix. | issueKey | | issues_mark_wont_fix | Marks multiple issues as Won't Fix in a single operation. | issueKeys | | issue_resolve | Marks an issue as resolved (RESOLVE transition). | issueKey | | issue_reopen | Reopens a resolved issue (REOPEN transition). | issueKey |

Available filters for issues: projectKey, componentKeys, severities (INFO/MINOR/MAJOR/CRITICAL/BLOCKER), statuses, resolutions, types, rules, tags, assignees, languages, branch, pullRequest, createdAfter, createdBefore, resolved, inNewCodePeriod, assigned, page, pageSize, s (sort field), asc.

Security hotspots

| Tool | Description | Required params | | ----------------------- | ---------------------------------------------------- | ------------------- | | hotspots | Searches for security hotspots in a project. | — | | hotspot | Gets the full details of a hotspot by its key. | hotspotKey | | hotspot_update_status | Updates a hotspot status (TO_REVIEW / REVIEWED). | hotspot, status |

Measures and metrics

| Tool | Description | Required params | | --------------------- | ------------------------------------------------- | ----------------------------- | | measures_component | Gets the measures of a specific component. | component, metricKeys | | measures_components | Gets measures for multiple components at once. | componentKeys, metricKeys | | measures_history | Gets the metric history of a component over time. | component, metrics | | metrics | Lists all available metrics in SonarQube. | — |

Common metric keys: coverage, bugs, vulnerabilities, code_smells, duplicated_lines_density, ncloc, reliability_rating, security_rating, sqale_rating.

Quality Gates

| Tool | Description | Required params | | --------------------- | ------------------------------------------------------- | --------------- | | quality_gates | Lists all Quality Gates defined in SonarQube. | — | | quality_gate | Gets the details of a Quality Gate by its ID. | id | | quality_gate_status | Gets the Quality Gate status of a project (OK / ERROR). | projectKey |

Components

| Tool | Description | Required params | | ---------------- | -------------------------------------------------------------------- | --------------- | | components | Searches for components (projects, directories, files) in SonarQube. | — | | component_show | Shows information about a specific component by its key. | key | | component_tree | Gets the sub-component tree of a parent component. | component |

Component types (qualifiers): TRK (project), DIR (directory), FIL (file), UTS (unit test), BRC (branch), APP, VW, SVW, LIB.

Source code

| Tool | Description | Required params | | ---------------- | ------------------------------------------------------- | --------------- | | source_code | Gets the annotated source code of a file by its key. | key | | scm_blame | Gets SCM blame information (line authorship) of a file. | key | | get_raw_source | Gets the raw plain-text source code of a file. | key |

Rules

| Tool | Description | Required params | | -------------- | -------------------------------------------------------------------------------------------------- | --------------- | | show_rule | Gets the details of a single SonarQube rule by its key (e.g. java:S1234). | key | | search_rules | Searches for rules with optional filters by language, tags, types, severities, or quality profile. | — |

Duplications

| Tool | Description | Required params | | ------------------------- | --------------------------------------------------------------- | --------------- | | get_duplications | Gets the code duplication blocks for a specific file. | key | | search_duplicated_files | Lists files in a project sorted by highest duplication density. | projectKey |

Languages

| Tool | Description | Optional params | | ---------------- | ------------------------------------------------------- | ------------------ | | list_languages | Lists all programming languages supported by SonarQube. | q (search), ps |

Quality Profiles

| Tool | Description | Required params | | --------------------------- | ----------------------------------------------------------------------- | --------------- | | list_quality_profiles | Lists all quality profiles, optionally filtered by language or project. | — | | get_quality_profile_rules | Lists the rules activated in a specific quality profile. | qprofile |

Local development

If you want to contribute or run the server from source:

# Clone the repository
git clone https://github.com/GonzaloRando03/sonarqube-mcp-server.git
cd sonarqube-mcp-server

# Install dependencies
npm install

# Run in development mode (no build required)
SONARQUBE_URL=https://sonarcloud.io SONARQUBE_TOKEN=squ_xxx npm run dev

# Build
npm run build

Project structure

mi_mcp/
├── src/
│   ├── index.ts                        # Entry point: initializes the MCP server
│   ├── domain/                         # Domain layer (interfaces, types, errors)
│   │   ├── config/                     # SonarQubeApiConfig
│   │   ├── errors/                     # SonarQubeAPIError, SonarQubeErrorType
│   │   └── <domain>/                   # Domain-specific types (issue, hotspot, measure…)
│   ├── application/
│   │   ├── use-cases/                  # One Use Case per business operation
│   │   │   ├── issue/                  # GetIssues, AddCommentToIssue, AssignIssue…
│   │   │   ├── hotspot/                # SearchHotspots, GetHotspot, UpdateHotspotStatus
│   │   │   ├── measure/                # GetComponentMeasures, GetMeasuresHistory…
│   │   │   └── …                       # (project, quality-gate, source, rule, etc.)
│   │   └── services/                   # Optional application services
│   └── infrastructure/
│       ├── controllers/                # HTTP adapters to the SonarQube API
│       │   ├── sonarQubeApiBaseController.ts  # fetch + auth + error handling
│       │   └── <domain>Controller.ts
│       ├── mcp/
│       │   ├── container.ts            # IoC: instantiates all use cases and controllers
│       │   ├── toolList.ts             # JSON schema definition for every tool
│       │   ├── toolRouter.ts           # Routes tool names to the right handler
│       │   └── handlers/               # One handler per domain
│       └── utils/                      # withErrorHandling, classifyHttpError
├── tests/                              # Integration tests (Vitest)
├── package.json
└── tsconfig.json

Tests

# Run all tests once
npm test

# Watch mode (re-runs on save)
npm run test:watch

# Visual UI in the browser
npm run test:ui

Tests use Vitest and live in tests/. Each file covers one domain (e.g. issue.test.ts, hotspot.test.ts, measure.test.ts…).