Sonarqube MCP

SonarQube MCP Integration

Leverage SonarQube and SonarCloud capabilities directly through the Model Context Protocol (MCP) server to enforce code quality, discover issues, and run pre-push analysis inside the agent workflow.

Overview

This skill provides instructions and patterns for using the SonarQube MCP Server tools. It enables automated workflows for:

• Checking quality gate status before merges or deployments
• Discovering and triaging issues by severity and project
• Analyzing code snippets locally before committing (shift-left)
• Understanding SonarQube rules with full documentation

When to Use

Use this skill when:

• The user wants to check if a project passes its quality gate before merging a PR
• The user wants to find critical or blocker issues in one or more SonarQube projects
• The user wants to analyze a code snippet for issues before pushing to CI
• The user wants to understand why a specific Sonar rule flagged their code
• The user asks for pre-commit or pre-push quality feedback

Trigger phrases: "check quality gate", "sonarqube quality gate", "find sonar issues", "search sonar issues", "analyze code with sonar", "check sonar rule", "sonarcloud issues", "pre-push sonar check", "sonar pre-commit"

Prerequisites and Setup

The plugin includes a .mcp.json that starts the SonarQube MCP Server automatically via Docker. Before using this skill, set the required environment variables:

SonarQube Server (remote or local):

export SONARQUBE_TOKEN="squ_your_token"
export SONARQUBE_URL="https://sonarqube.mycompany.com"  # or http://host.docker.internal:9000 for local Docker

SonarCloud:

export SONARQUBE_TOKEN="squ_your_token"
export SONARQUBE_ORG="your-org-key"   # required for SonarCloud
# SONARQUBE_URL is not needed for SonarCloud

Requirements:

• Docker must be installed and running
• SONARQUBE_TOKEN is always required
• SONARQUBE_URL is required for SonarQube Server (use host.docker.internal for local instances)
• SONARQUBE_ORG is required for SonarCloud (omit SONARQUBE_URL in that case)

Quick Start

1. Set your SonarQube/SonarCloud credentials:

   # SonarQube Server
   export SONARQUBE_TOKEN="squ_your_token"
   export SONARQUBE_URL="https://sonarqube.mycompany.com"
   
   # SonarCloud
   export SONARQUBE_TOKEN="squ_your_token"
   export SONARQUBE_ORG="your-org-key"

2. Verify MCP tool availability:

   • Tool names follow the pattern: mcp__sonarqube-mcp__<tool-name>

3. If the MCP server fails to start, check:

   • Docker is running
   • Environment variables are set
   • Reference: mcp/sonarqube on Docker Hub

Reference Documents

• references/metrics.md — Common SonarQube metrics and their meaning
• references/severity-levels.md — Sonar severity levels and impact categories
• references/best-practices.md — Workflows for PR checks and pre-commit analysis
• references/llm-context.md — Tool selection guide and parameter mapping for LLM agents

Instructions

Step 1: Identify the Required Operation

Determine which operation the user needs:

If the user's intent is ambiguous, ask for the project key and the goal before proceeding.

Step 2: Quality Gate Monitoring

Use get_project_quality_gate_status to verify a project meets its quality standards.

Parameters:

• projectKey (string) — Project key in SonarQube/SonarCloud
• pullRequest (string, optional) — Pull request ID for PR-specific gate check
• analysisId (string, optional) — Specific analysis ID

Note: There is no branch parameter on this tool. Without a pullRequest or analysisId, the tool returns the quality gate status for the default branch.

Pattern — Check default branch gate:

{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey": "my-application"
  }
}

Pattern — Check PR gate before merge:

{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey": "backend-service",
    "pullRequest": "456"
  }
}

Interpreting the response:

• status: "OK" — Gate passed, safe to merge/deploy
• status: "ERROR" — Gate failed; check conditions array for failing metrics
• Each condition shows: metricKey, actualValue, errorThreshold, comparator

For more on metric keys, see references/metrics.md.

Step 3: Issue Discovery and Triaging

Use search_sonar_issues_in_projects to find and prioritize issues.

Parameters:

• projects (array, optional) — List of project keys; omit to search all accessible projects
• severities (array, optional) — Filter: BLOCKER, HIGH, MEDIUM, LOW, INFO
• pullRequestId (string, optional) — Limit search to a specific PR
• p (integer, optional) — Page number (default: 1)
• ps (integer, optional) — Page size (default: 100, max: 500)

Pattern — Find blockers and critical issues:

{
  "name": "search_sonar_issues_in_projects",
  "arguments": {
    "projects": ["my-backend", "my-frontend"],
    "severities": ["BLOCKER", "HIGH"],
    "p": 1,
    "ps": 50
  }
}

Pattern — Search issues in a PR:

{
  "name": "search_sonar_issues_in_projects",
  "arguments": {
    "projects": ["my-service"],
    "pullRequestId": "123",
    "severities": ["HIGH", "MEDIUM"],
    "p": 1,
    "ps": 100
  }
}

Managing issues with change_sonar_issue_status:

Use this to mark false positives or accepted technical debt:

{
  "name": "change_sonar_issue_status",
  "arguments": {
    "key": "AY1234",
    "status": "falsepositive",
    "comment": "This pattern is safe in our context because..."
  }
}

Valid statuses: falsepositive (not a real issue), accept (acknowledged technical debt), reopen (reset to open)

Always present the list of issues to the user before changing their status. Never autonomously mark issues as false positives without explicit user confirmation.

Step 4: Pre-Push Analysis (Shift Left)

Use analyze_code_snippet to run SonarQube analysis on code before committing.

Parameters:

• projectKey (string) — Project key for context
• fileContent (string, required) — Full content of the file to analyze
• language (string, optional) — Language hint for better accuracy
• codeSnippet (string, optional) — Narrow results to a specific sub-range within fileContent

Supported languages: javascript, typescript, python, java, go, php, cs, cpp, kotlin, ruby, scala, swift

Pattern — Analyze TypeScript file before commit:

{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey": "my-typescript-app",
    "fileContent": "async function fetchUser(id: string) {\n  const query = `SELECT * FROM users WHERE id = ${id}`;\n  return db.execute(query);\n}",
    "language": "typescript"
  }
}

Pattern — Analyze Python file:

{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey": "my-python-service",
    "fileContent": "import pickle\n\ndef load_model(path):\n    with open(path, 'rb') as f:\n        return pickle.load(f)",
    "language": "python"
  }
}

Response interpretation:

• Each issue includes: ruleKey, severity, clean code attribute, impact category, line number, quick fix availability
• Address CRITICAL and HIGH severity issues before committing
• Use show_rule with the ruleKey value for any unfamiliar rule