SonarQube MCP server for AI agents

The SonarQube MCP Server enables AI assistants to access SonarQube's code quality analysis capabilities through the Model Context Protocol. This integration provides insights into metrics, issues, security hotspots, and more, helping you maximize the value of your code quality tools.

Installation

Using NPX (Recommended)

The simplest way to integrate the SonarQube MCP Server with Claude Desktop is through npx:

{
  "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)"
      }
    }
  }
}

Using Docker

For production environments, Docker provides a reliable deployment method:

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

Configuration

Authentication Methods

Choose one of the following authentication methods:

Token Authentication (Recommended)

{
  "env": {
    "SONARQUBE_TOKEN": "your-token-here"
  }
}

Basic Authentication

{
  "env": {
    "SONARQUBE_USERNAME": "your-username",
    "SONARQUBE_PASSWORD": "your-password"
  }
}

System Passcode

{
  "env": {
    "SONARQUBE_PASSCODE": "your-system-passcode"
  }
}

Required Settings

For SonarCloud:

SONARQUBE_URL: Set to https://sonarcloud.io
SONARQUBE_ORGANIZATION: Your organization key (required)
SONARQUBE_TOKEN: Your authentication token

For SonarQube Server:

SONARQUBE_URL: Your SonarQube instance URL
Authentication credentials (token, username/password, or passcode)

Optional Settings

LOG_FILE: Path to write logs (e.g., /tmp/sonarqube-mcp.log)
LOG_LEVEL: Logging level (DEBUG, INFO, WARN, ERROR)

Usage Examples

Project Management

"List all my SonarQube projects"
"Show me the code coverage for project xyz"

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"

Component Navigation

"Find all files containing 'UserService' in their name"
"List all test files in my project"
"Show me the directory structure of src/main"

Issue Management

"Assign issue PROJECT-123 to john.doe"
"Mark issue ABC-789 as false positive with comment: 'Test code only'"
"Add comment to issue XYZ-111: 'Fixed in commit abc123'"

Quality Monitoring

"Check the quality gate status for my main project"
"Show me the code coverage history for the last month"

Security Hotspot Review

"Find all security hotspots that need review in project xyz"
"Show me hotspots in the authentication module"
"Get details for hotspot HSP-12345"

Troubleshooting

Common Issues

Authentication Errors

"Authentication failed": Verify your token is valid and not expired
"No SonarQube authentication configured": Ensure you've set one of the authentication methods

Resource Not Found Errors

"Resource not found": Verify the project key exists and you have access to it

Network and Connection Errors

"Connection refused": Check that the SonarQube server is running and the URL is correct
"Network error": Verify your network connection and server accessibility

Debugging Tips

Enable debug logging: LOG_LEVEL=DEBUG
Test connection with the ping tool: sonarqube.ping
Verify permissions by listing accessible projects: sonarqube.projects

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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)"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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)"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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)"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect