mcp-sonarqube

SonarQube MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to SonarQube code quality, security, and project analytics data.

Features

• Project Listing: Get comprehensive project information with quality metrics
• Project Metrics: Fetch detailed quality metrics including coverage, duplication, maintainability
• Issue Management: List and analyze code quality issues with filtering capabilities
• Security Analysis: Get detailed security vulnerability and hotspot information
• Quality Gates: Check quality gate status and conditions
• Historical Analysis: View project evolution and quality trends over time

Installation

npm (Recommended)

# Global installation
npm install -g mcp-sonarqube

# Local installation in your project
npm install mcp-sonarqube

From Source

• Clone the repository:

git clone https://github.com/akhilthomas236/sonarqube-mcp-npm.git
cd sonarqube-mcp

• Install dependencies:

npm install

• Build the project:

npm run build

Quick Start

1. Install the package

npm install -g mcp-sonarqube

2. Set up environment variables

export SONARQUBE_URL="http://your-sonarqube-instance:9000"
export SONARQUBE_TOKEN="your-sonarqube-token"

3. Run as MCP Server

mcp-sonarqube

4. VS Code Integration

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "sonarqube": {
      "command": "npx",
      "args": ["mcp-sonarqube"],
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "your-sonarqube-token-here"
      }
    }
  }
}

Then use with GitHub Copilot:

@copilot List all projects in our SonarQube instance
@copilot Show me quality metrics for project "my-app"
@copilot What are the critical security vulnerabilities in project "api-service"?

Getting a SonarQube Token

• Log in to your SonarQube instance
• Go to User > My Account > Security
• Generate a new token with appropriate permissions
• Use this token as your SONARQUBE_TOKEN

Usage

Running the Server

npm start

The server runs on stdio transport and communicates via the Model Context Protocol.

Available Tools

1. list_projects

Lists all projects in your SonarQube instance with key metrics.

Parameters:

• search (optional): Filter projects by name or key
• qualityGate (optional): Filter by quality gate status (OK, WARN, ERROR)
• organization (optional): Filter by organization (SonarCloud)

2. get_project_metrics

Get comprehensive metrics for a specific project.

Parameters:

• projectKey (required): The SonarQube project key
• branch (optional): Branch name (defaults to main branch)
• metrics (optional): Comma-separated list of specific metrics

3. list_issues

List code quality issues with filtering options.

Parameters:

• projectKey (required): The SonarQube project key
• branch (optional): Branch name
• types (optional): Issue types (BUG, VULNERABILITY, CODE_SMELL)
• severities (optional): Severities (BLOCKER, CRITICAL, MAJOR, MINOR, INFO)
• statuses (optional): Statuses (OPEN, CONFIRMED, REOPENED, RESOLVED, CLOSED)
• assignees (optional): Assignee usernames
• tags (optional): Issue tags
• limit (optional): Maximum number of issues (default: 50)

4. get_security_vulnerabilities

Get detailed security vulnerability analysis.

Parameters:

• projectKey (required): The SonarQube project key
• branch (optional): Branch name
• severities (optional): Filter by severities
• statuses (optional): Filter by statuses
• assigned (optional): Filter by assigned/unassigned
• limit (optional): Maximum number of vulnerabilities (default: 50)

5. get_quality_gate

Check quality gate status and conditions.

Parameters:

• projectKey (required): The SonarQube project key
• branch (optional): Branch name

6. get_analysis_history

View historical analysis data and trends.

Parameters:

• projectKey (required): The SonarQube project key
• branch (optional): Branch name
• from (optional): Start date (YYYY-MM-DD)
• to (optional): End date (YYYY-MM-DD)
• limit (optional): Maximum number of analyses (default: 10)

Development

Project Structure

src/
├── index.ts                    # MCP server entry point
├── services/
│   └── sonarqube-client.ts    # SonarQube API client
├── tools/                     # MCP tool implementations
│   ├── list-projects.ts
│   ├── get-project-metrics.ts
│   ├── list-issues.ts
│   ├── get-security-vulnerabilities.ts
│   ├── get-quality-gate.ts
│   └── get-analysis-history.ts
├── types/
│   └── sonarqube.ts          # TypeScript type definitions
└── utils/
    └── formatting.ts         # Utility functions

Scripts

• npm run build - Build the TypeScript project
• npm run dev - Run in development mode with ts-node
• npm start - Start the MCP server
• npm test - Run tests

Adding New Tools

• Create a new tool file in src/tools/
• Implement the tool schema and handler function
• Add the tool to the imports and tools array in src/index.ts
• Add a case for the tool in the CallTool handler

VS Code Integration

To use this MCP server with VS Code and Copilot:

Method 1: Using npx (Recommended)

• Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "sonarqube": {
      "command": "npx",
      "args": ["mcp-sonarqube"],
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "your-token-here"
      }
    }
  }
}

Method 2: Using local installation

If you have the package installed locally:

{
  "servers": {
    "sonarqube": {
      "command": "node",
      "args": ["./node_modules/mcp-sonarqube/dist/index.js"],
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "your-token-here"
      }
    }
  }
}

Method 3: Global installation

If you have the package installed globally:

{
  "servers": {
    "sonarqube": {
      "command": "mcp-sonarqube",
      "env": {
        "SONARQUBE_URL": "http://localhost:9000",
        "SONARQUBE_TOKEN": "your-token-here"
      }
    }
  }
}

• Install the MCP extension for VS Code
• The SonarQube tools will be available in Copilot Chat

Examples

Check Project Quality

@copilot Use the SonarQube tools to give me a quality overview of project "my-app"

Security Analysis

@copilot Show me all security vulnerabilities in project "my-app" that are CRITICAL or BLOCKER

Quality Gate Status

@copilot Check if project "my-app" passes its quality gate

Historical Trends

@copilot Show me the quality trends for project "my-app" over the last month

Error Handling

The server provides detailed error messages for common issues:

• Missing environment variables
• Invalid project keys
• SonarQube connection issues
• Authentication failures
• Invalid parameters

Troubleshooting

"Server exited before responding to initialize request"

If you encounter this error in VS Code or when using the MCP server, try these solutions:

• Test the server directly first:

  # Test if the server starts correctly
  node dist/index.js
  # Should output: "SonarQube MCP Server started successfully"
  
  # Test with an MCP initialize request
  echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | node dist/index.js
  

• For VS Code integration issues:

  • Make sure the package is installed globally: npm install -g mcp-sonarqube
  • Try using the full path instead of npx:

    {
      "servers": {
        "sonarqube": {
          "command": "node",
          "args": ["/path/to/global/node_modules/mcp-sonarqube/dist/index.js"],
          "env": {
            "SONARQUBE_URL": "http://localhost:9000",
            "SONARQUBE_TOKEN": "your-token"
          }
        }
      }
    }
    

  • Restart VS Code after changing the MCP configuration

• For npx issues:

  • Clear npm cache: npm cache clean --force
  • Reinstall the package: npm uninstall -g mcp-sonarqube && npm install -g mcp-sonarqube
  • Check Node.js version (requires Node.js 18+)

• Environment variable issues:

  • Ensure SONARQUBE_URL and SONARQUBE_TOKEN are properly set
  • Test connection: curl -u your-token: $SONARQUBE_URL/api/projects/search

SonarQube API Parameter Errors

If you encounter API errors related to invalid parameters:

• "additionalFields components must be one of..."

  • This error has been fixed in version 1.0.2+
  • Update to the latest version: npm update -g mcp-sonarqube
  • The server now uses valid additionalFields values: rules,users,comments

• Invalid parameter values:

  • Check that your SonarQube version supports the API endpoints being used
  • Some parameters may have different valid values in different SonarQube versions
  • Refer to your SonarQube instance's API documentation at: {SONARQUBE_URL}/web_api

Network and Authentication Issues

• Connection errors:

  • Verify SonarQube URL is accessible
  • Check firewall settings
  • Ensure SonarQube server is running

• Authentication errors:

  • Verify token is valid and has appropriate permissions
  • Check token expiration
  • Ensure token has at least "Browse" permission on projects

• SSL/TLS issues:

  • For self-signed certificates, you may need to set NODE_TLS_REJECT_UNAUTHORIZED=0 (not recommended for production)

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• Submit a pull request

License

MIT License - see LICENSE file for details

Links

• npm Package: https://www.npmjs.com/package/mcp-sonarqube
• GitHub Repository: https://github.com/akhilthomas236/sonarqube-mcp-npm
• SonarQube Documentation: https://docs.sonarqube.org/
• Model Context Protocol: https://modelcontextprotocol.io/

Support

For issues and questions:

• Check the SonarQube API documentation
• Verify your token permissions
• Ensure network connectivity to SonarQube
• Check the server logs for detailed error messages
• Create an issue on GitHub