README - SonarQube MCP Server by sapientpants

SonarQube MCP Server

A Model Context Protocol (MCP) server that integrates with SonarQube to provide AI assistants with access to code quality metrics, issues, and analysis results.

Overview

The SonarQube MCP Server enables AI assistants to interact with SonarQube's code quality analysis capabilities through the Model Context Protocol. This integration allows AI assistants to:

📊 Retrieve code metrics and analysis results - Access detailed quality metrics for your projects
🐛 Access and filter issues - Search and filter code issues by severity, type, status, and more
✅ Check quality gates - Monitor whether projects meet quality standards
📈 Analyze project quality over time - Track metrics history and trends
🔍 View source code with issues - See problematic code with highlighted issues
🏥 Monitor system health - Check SonarQube instance status and availability

Quick Start

Prerequisites

Claude Desktop installed
A SonarQube instance or SonarCloud account
A SonarQube/SonarCloud authentication token

1. Get Your SonarQube Token

For SonarCloud:

Log in to SonarCloud
Go to My Account → Security
Generate a new token

For SonarQube:

Log in to your SonarQube instance
Go to My Account → Security
Generate a new token

2. Configure Claude Desktop

Open Claude Desktop
Go to Settings → Developer → Edit Config
Add the SonarQube server configuration:

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-mcp-server@latest"],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_TOKEN": "your-token-here",
        "SONARQUBE_ORGANIZATION": "your-org (for SonarCloud)"
      }
    }
  }
}

Restart Claude Desktop

3. Start Using

Ask Claude to analyze your SonarQube projects:

"List all my SonarQube projects"
"Show me critical issues in project xyz"
"What's the code coverage for my main project?"
"Check the quality gate status"

Installation

NPX (Recommended)

The simplest way to use the SonarQube MCP Server is through npx:

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-mcp-server@latest"],
      "env": {
        "SONARQUBE_URL": "https://sonarqube.example.com",
        "SONARQUBE_TOKEN": "your-sonarqube-token",
        "SONARQUBE_ORGANIZATION": "your-organization-key"
      }
    }
  }
}

Docker

Run the server using Docker:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORGANIZATION",
        "sapientpants/sonarqube-mcp-server"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarqube.example.com",
        "SONARQUBE_TOKEN": "your-sonarqube-token",
        "SONARQUBE_ORGANIZATION": "your-organization-key"
      }
    }
  }
}

Local Development

For development or customization:

{
  "mcpServers": {
    "sonarqube": {
      "command": "node",
      "args": ["/path/to/sonarqube-mcp-server/dist/index.js"],
      "env": {
        "SONARQUBE_URL": "https://sonarqube.example.com",
        "SONARQUBE_TOKEN": "your-sonarqube-token",
        "SONARQUBE_ORGANIZATION": "your-organization-key"
      }
    }
  }
}

Configuration

Environment Variables

Variable	Description	Required	Default
`SONARQUBE_TOKEN`	Authentication token for SonarQube API access	✅ Yes	-
`SONARQUBE_URL`	URL of your SonarQube instance	❌ No	`https://sonarcloud.io`
`SONARQUBE_ORGANIZATION`	Organization key (required for SonarCloud)	❌ No*	-

*Required when using SonarCloud

SonarCloud vs SonarQube

For SonarCloud:

Set SONARQUBE_URL to https://sonarcloud.io
SONARQUBE_ORGANIZATION is required

For SonarQube Server:

Set SONARQUBE_URL to your instance URL
SONARQUBE_ORGANIZATION is typically not needed

Available Tools

Project Management

`projects`

List all SonarQube projects with pagination support.

Parameters:

page (optional): Page number for results pagination
page_size (optional): Number of items per page

Metrics and Measures

`metrics`

Get available metrics from SonarQube.

Parameters:

page (optional): Page number for results pagination
page_size (optional): Number of items per page

`measures_component`

Get measures for a specific component.

Parameters:

component (required): Component key
metric_keys (required): Array of metric keys
additional_fields (optional): Additional fields to return
branch (optional): Branch name
pull_request (optional): Pull request key
period (optional): Period index

`measures_components`

Get measures for multiple components.

Parameters:

component_keys (required): Array of component keys
metric_keys (required): Array of metric keys
Additional parameters same as measures_component
page (optional): Page number
page_size (optional): Items per page

`measures_history`

Get measures history for a component.

Parameters:

component (required): Component key
metrics (required): Array of metric keys
from (optional): Start date (YYYY-MM-DD)
to (optional): End date (YYYY-MM-DD)
branch (optional): Branch name
pull_request (optional): Pull request key
page (optional): Page number
page_size (optional): Items per page

Issue Management

`issues`

Get issues from a SonarQube project with extensive filtering options.

Parameters:

project_key (required): The unique identifier for the project
severity (optional): Filter by severity (INFO, MINOR, MAJOR, CRITICAL, BLOCKER)
statuses (optional): Filter by status array
resolutions (optional): Filter by resolution array
types (optional): Filter by type array
rules (optional): Array of rule keys
tags (optional): Array of tags
created_after (optional): Issues created after date (YYYY-MM-DD)
created_before (optional): Issues created before date (YYYY-MM-DD)
assignees (optional): Array of assignee logins
authors (optional): Array of author logins
languages (optional): Array of languages
And many more filtering options...

Quality Gates

`quality_gates`

List available quality gates.

No parameters required

`quality_gate`

Get quality gate conditions.

Parameters:

id (required): Quality gate ID

`project_quality_gate_status`

Get project quality gate status.

Parameters:

project_key (required): Project key
branch (optional): Branch name
pull_request (optional): Pull request key

Source Code

`source_code`

View source code with issues highlighted.

Parameters:

key (required): File key
from (optional): Start line
to (optional): End line
branch (optional): Branch name
pull_request (optional): Pull request key

`scm_blame`

Get SCM blame information for source code.

Parameters:

Same as source_code

System Monitoring

`system_health`

Get the health status of the SonarQube instance.

No parameters required

`system_status`

Get the status of the SonarQube instance.

No parameters required

`system_ping`

Ping the SonarQube instance to check if it is up.

No parameters required

Usage Examples

Basic Project Analysis

"List all my SonarQube projects"
"Show me the code coverage for project xyz"
"What metrics are available for analysis?"

Issue Investigation

"Show me all critical bugs in project abc"
"Find security vulnerabilities in the main branch"
"List all code smells created in the last week"
"Show unresolved issues assigned to john.doe"

Quality Monitoring

"Check the quality gate status for my main project"
"Show me the code coverage history for the last month"
"What are the quality gate conditions?"
"Compare metrics between develop and main branches"

Source Code Analysis

"Show me the source code for file xyz with issues highlighted"
"Get blame information for the problematic file"
"View issues in the authentication module"

System Health

"Check if SonarQube is running"
"What's the health status of the SonarQube instance?"
"Show me the system status"

Architecture

The SonarQube MCP Server follows a modular architecture:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│  MCP Server      │────▶│  SonarQube API  │
│  (MCP Client)   │◀────│  (index.ts)      │◀────│                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  SonarQube       │
                        │  Client          │
                        │  (sonarqube.ts)  │
                        └──────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  API Module      │
                        │  (api.ts)        │
                        └──────────────────┘

Key Components

MCP Server (index.ts): Main entry point that initializes the MCP server and registers all available tools
SonarQube Client (sonarqube.ts): Handles business logic and parameter transformation
API Module (api.ts): Manages HTTP requests to the SonarQube API
Type Definitions: TypeScript interfaces for type safety

Data Flow

MCP clients make requests through registered tools
Tool handlers validate and transform parameters
SonarQube client methods process the requests
API module executes HTTP requests
Responses are formatted and returned to the client

Development

Prerequisites

Node.js 20 or higher
pnpm 10.7.0 or higher
Docker (for container builds)

Setup

Clone the repository:

git clone https://github.com/sapientpants/sonarqube-mcp-server.git
cd sonarqube-mcp-server

Install dependencies:

pnpm install

Build the project:

pnpm build

Development Commands

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode with auto-reload
pnpm dev

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Lint the code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Check types
pnpm check-types

# Format code
pnpm format

# Run all validations
pnpm validate

# Inspect MCP schema
pnpm inspect

Testing

The project uses Jest for testing with:

Unit tests for all major components
Mocked HTTP responses using nock
Coverage reporting
TypeScript support

Run specific test files:

NODE_ENV=test NODE_OPTIONS='--experimental-vm-modules --no-warnings' jest src/__tests__/file-name.test.ts

Code Quality

The project maintains high code quality through:

TypeScript for type safety
ESLint for code linting
Prettier for code formatting
Jest for testing
SonarCloud for continuous code analysis

Troubleshooting

Common Issues

"Authentication failed"

Cause: Invalid or expired token
Solution: Generate a new token in SonarQube/SonarCloud

"Project not found"

Cause: Incorrect project key or insufficient permissions
Solution: Verify the project key and check token permissions

"Organization required"

Cause: Using SonarCloud without organization parameter
Solution: Add SONARQUBE_ORGANIZATION to your configuration

"Connection refused"

Cause: Incorrect URL or network issues
Solution: Verify SONARQUBE_URL and network connectivity

FAQ

Q: Can I use this with both SonarQube and SonarCloud? A: Yes! Set the appropriate SONARQUBE_URL and include SONARQUBE_ORGANIZATION for SonarCloud.

Q: What permissions does my token need? A: The token needs "Execute Analysis" permission and access to the projects you want to analyze.

Q: How do I filter issues by multiple criteria? A: The issues tool supports extensive filtering. You can combine multiple parameters like severity, type, status, and date ranges.

Q: Can I analyze pull requests? A: Yes! Many tools support branch and pull_request parameters for branch and PR analysis.

Contributing

We welcome contributions! Please see our for details.

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Write tests for new features
Update documentation as needed
Follow the existing code style
Ensure all tests pass
Add appropriate error handling

sonarqube-mcp-server

SonarQube MCP Server

Overview

Quick Start

Prerequisites

1. Get Your SonarQube Token

2. Configure Claude Desktop

3. Start Using

Installation

NPX (Recommended)

Docker

Local Development

Configuration

Environment Variables

SonarCloud vs SonarQube

Available Tools

Project Management

projects

Metrics and Measures

metrics

measures_component

measures_components

measures_history

Issue Management

issues

Quality Gates

quality_gates

quality_gate

project_quality_gate_status

Source Code

source_code

scm_blame

System Monitoring

system_health

system_status

system_ping

Usage Examples

Basic Project Analysis

Issue Investigation

Quality Monitoring

Source Code Analysis

System Health

Architecture

Key Components

Data Flow

Development

Prerequisites

Setup

Development Commands

Testing

Code Quality

Troubleshooting

Common Issues

"Authentication failed"

"Project not found"

"Organization required"

"Connection refused"

FAQ

Contributing

How to Contribute

Development Guidelines

License

External Resources

SonarQube Documentation

Model Context Protocol

`projects`

`metrics`

`measures_component`

`measures_components`

`measures_history`

`issues`

`quality_gates`

`quality_gate`

`project_quality_gate_status`

`source_code`

`scm_blame`

`system_health`

`system_status`

`system_ping`