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
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"
Verify MCP tool availability:
Tool names follow the pattern:
mcp__sonarqube-mcp__
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:
User Intent
Tool to Use
Check if project passes quality gate
get_project_quality_gate_status
Find critical issues in a project
search_sonar_issues_in_projects
Analyze code before committing
analyze_code_snippet
Understand a flagged rule
show_rule
Get detailed project metrics
get_component_measures
Mark an issue as false positive
change_sonar_issue_status
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
Step 5: Rule Education
Use
show_rule
to understand why a rule exists and how to fix flagged code.
Parameters:
key
(string) — Rule key in format
:
(e.g.,
typescript:S1082
,
java:S2068
)
Pattern — Get rule documentation:
{
"name"
:
"show_rule"
,
"arguments"
:
{
"key"
:
"typescript:S1082"
}
}
Response includes:
rule name, type, severity, full description, tags (e.g.,
cwe
,
owasp-a2
), language, remediation effort estimate, code examples (non-compliant vs compliant).
Step 6: Get Component Measures
Use
get_component_measures
to retrieve detailed metrics for a project, directory, or file.
Parameters:
projectKey
(string) — Project key in SonarQube/SonarCloud
pullRequest
(string, optional) — PR ID for PR-scoped metrics
metricKeys
(array) — List of metric keys to retrieve
Common metric keys:
coverage
,
bugs
,
vulnerabilities
,
code_smells
,
complexity
,
cognitive_complexity
,
ncloc
,
duplicated_lines_density
,
new_coverage
,
new_bugs
Pattern — Project health dashboard:
{
"name"
:
"get_component_measures"
,
"arguments"
:
{
"projectKey"
:
"my-project-key"
,
"metricKeys"
:
[
"coverage"
,
"bugs"
,
"vulnerabilities"
,
"code_smells"
,
"ncloc"
]
}
}
For full metric reference, see
references/metrics.md
.
Step 7: Present Results to User
After each tool call:
Summarize findings in human-readable form
Flag issues that require attention (BLOCKER, HIGH severity)
Propose next actions based on findings
Wait for user confirmation before taking remediation steps (e.g., changing issue status, modifying code)
Examples
Example 1: Pre-Merge Quality Gate Check
User request:
"Check if the quality gate passes for project
backend-api
on PR #234"
{
"name"
:
"get_project_quality_gate_status"
,
"arguments"
:
{
"projectKey"
:
"backend-api"
,
"pullRequest"
:
"234"
}
}
If gate fails:
Extract failing conditions, present them to the user, then use
search_sonar_issues_in_projects
filtered by the same PR to show the actual issues.
Example 2: Shift-Left Analysis Before Push
User request:
"Analyze this Go function before I push it"
{
"name"
:
"analyze_code_snippet"
,
"arguments"
:
{
"projectKey"
:
"my-go-service"
,
"fileContent"
:
"func handler(w http.ResponseWriter, r *http.Request) {\n id := r.URL.Query().Get(\"id\")\n query := fmt.Sprintf(\"SELECT * FROM orders WHERE id = %s\", id)\n rows, _ := db.Query(query)\n // ...\n}"
,
"language"
:
"go"
}
}
Present findings → for each issue, optionally call
show_rule
with the
ruleKey
value to explain the fix.
Example 3: Triage BLOCKER Issues in a Project
User request:
"Show me all blocker issues in
payment-service
"
{
"name"
:
"search_sonar_issues_in_projects"
,
"arguments"
:
{
"projects"
:
[
"payment-service"
]
,
"severities"
:
[
"BLOCKER"
]
,
"p"
:
1
,
"ps"
:
50
}
}
Group results by category (Security, Reliability, Maintainability) and present to user. Offer to call
show_rule
for unfamiliar rules.
Best Practices
Environment Setup
— Set credentials once per session; the MCP server automatically picks them up
Always check quality gate before merge
— Run
get_project_quality_gate_status
as part of any PR review workflow
Shift left on security issues
— Use
analyze_code_snippet
during development, not only in CI
Prioritize by severity
— Address BLOCKER and HIGH issues first; document decisions for MEDIUM and LOW
Use
show_rule
for unfamiliar keys
— Never dismiss a rule without understanding its intent
Paginate large result sets
— Use
p
and
ps
parameters; handle multi-page responses for complete coverage
Never change issue status autonomously
— Always present issues to the user and get explicit confirmation before calling
change_sonar_issue_status
Provide language hints
— Specify
language
in
analyze_code_snippet
for more accurate analysis
Constraints and Warnings
MCP server must be configured and running; verify tool availability before use
analyze_code_snippet
analyzes snippets in isolation — full project context may affect results in CI
Issue status changes (false positive, won't fix) require appropriate SonarQube permissions
SonarCloud and SonarQube Server APIs are mostly compatible but some features differ; check
references/llm-context.md
Pagination is required for projects with many issues; check
paging.total
and
paging.pageSize
in the response to determine whether to iterate further pages
Quality gate status reflects the last completed analysis — trigger a new analysis if the code has changed