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…).