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:

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

Projects

Issues

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

Measures and metrics

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

Quality Gates

Components

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

Source code

Rules

Duplications

Languages

Quality Profiles

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