sonarqube-api-mcp

Docker-free SonarQube MCP server for read-only access to the SonarQube Web API.

Run it with:

npx sonarqube-api-mcp

Requirements

• Node.js 20+

• SonarQube token with permission to browse the target project

• No Docker

This package uses the public SonarQube Web API only. It does not use private SonarQube UI GraphQL endpoints.

It is designed for coding-agent workflows like:

• "fix all new code issues"

• "fix all overall code issues"

• "fix issues for this SonarQube project name"

The server stays read-only: it fetches SonarQube issues, source context, rule details, and quality data so the calling agent can edit the checked-out repository.

Configuration

Configure the server entirely through environment variables in mcp.json.

Startup fails clearly when SONAR_HOST_URL or SONAR_TOKEN is missing.

Published package usage

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-api-mcp"],
      "env": {
        "SONAR_HOST_URL": "https://sonarqube.yourcompany.com",
        "SONAR_TOKEN": "YOUR_SONAR_TOKEN",
        "SONAR_PROJECT_KEY": "hvmb-app"
      }
    }
  }
}

Local package development

Build first:

npm install
npm run build

Then point your MCP client at the compiled entrypoint:

{
  "mcpServers": {
    "sonarqube-local": {
      "command": "node",
      "args": ["/absolute/path/to/sonarqube-api-mcp/dist/index.js"],
      "env": {
        "SONAR_HOST_URL": "https://sonarqube.yourcompany.com",
        "SONAR_TOKEN": "YOUR_SONAR_TOKEN",
        "SONAR_PROJECT_KEY": "hvmb-app"
      }
    }
  }
}

Default project key

Set SONAR_PROJECT_KEY once and omit projectKey from project-scoped tool calls.

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["-y", "sonarqube-api-mcp"],
      "env": {
        "SONAR_HOST_URL": "https://sonarqube.yourcompany.com",
        "SONAR_TOKEN": "YOUR_SONAR_TOKEN",
        "SONAR_PROJECT_KEY": "hvmb-app"
      }
    }
  }
}

Example tool input:

{
  "resolved": false,
  "severities": ["BLOCKER", "CRITICAL"]
}

Per-tool project override

Every project-scoped tool accepts projectKey or projectName, which override SONAR_PROJECT_KEY for that call.

{
  "projectKey": "another-project",
  "branch": "main",
  "metricKeys": ["coverage", "bugs", "vulnerabilities"]
}

If your infrastructure creates a SonarQube project per branch, pass the SonarQube project name directly:

{
  "projectName": "repo-name-feature-branch",
  "scope": "new_code"
}

If a name matches multiple projects, the tool returns candidates and asks the caller to retry with projectKey.

Tools

search_sonar_projects

Searches /api/projects/search to find project keys by SonarQube project name or key.

Inputs:

• query optional string

• pageSize optional number, defaults to 100

get_sonar_fix_plan

Gets unresolved issues grouped by file for agentic fixing workflows.

Use this for prompts like "fix all new code issues" or "fix all overall code issues".

Inputs:

• projectKey optional, falls back to SONAR_PROJECT_KEY

• projectName optional, resolved through /api/projects/search

• scope optional, new_code or overall, defaults to new_code

• branch optional

• pullRequest optional

• severities optional string array

• statuses optional string array

• types optional string array

• impactSeverities optional string array for newer SonarQube versions

• impactSoftwareQualities optional string array for newer SonarQube versions

• pageSize optional number, defaults to 100

• maxIssues optional number, defaults to 200

• includeSource optional boolean, defaults to true

• includeRules optional boolean, defaults to false

• contextLines optional number, defaults to 5

Example for new code:

{
  "projectName": "hvmb-app-feature-branch",
  "scope": "new_code",
  "includeSource": true,
  "includeRules": true
}

Example for overall code:

{
  "projectKey": "hvmb-app",
  "scope": "overall",
  "maxIssues": 500
}

Returns clean JSON with:

• resolved project identity

• issue count and truncation flag

• optional rule details keyed by rule key

• files sorted by issue count

• issues per file

• merged source ranges around affected lines

get_sonar_issue_context

Gets one issue plus surrounding source lines and optional rule details.

Inputs:

• issueKey required

• branch optional

• pullRequest optional

• contextLines optional number, defaults to 5

• includeRule optional boolean, defaults to true

search_sonar_issues

Searches /api/issues/search and handles pagination.

Inputs:

• projectKey optional, falls back to SONAR_PROJECT_KEY

• projectName optional, resolved through /api/projects/search

• branch optional

• pullRequest optional

• severities optional string array

• statuses optional string array

• types optional string array

• impactSeverities optional string array for newer SonarQube versions

• impactSoftwareQualities optional string array for newer SonarQube versions

• inNewCodePeriod optional boolean

• resolved optional boolean, defaults to false

• pageSize optional number, defaults to 100

Returns clean JSON with issue key, rule, severity, type, message, component, filePath, line, textRange, effort, status, and tags.

get_quality_gate_status

Calls /api/qualitygates/project_status.

Inputs:

• projectKey optional, falls back to SONAR_PROJECT_KEY

• projectName optional, resolved through /api/projects/search

• branch optional

• pullRequest optional

get_rule_details

Calls /api/rules/show.

Inputs:

• ruleKey required

get_component_measures

Calls /api/measures/component.

Inputs:

• projectKey optional, falls back to SONAR_PROJECT_KEY

• projectName optional, resolved through /api/projects/search

• metricKeys required string array

• branch optional

• pullRequest optional

get_sonar_sources

Calls /api/sources/lines.

Inputs:

• component required

• from optional number

• to optional number

• branch optional

• pullRequest optional

Errors

SonarQube API errors are wrapped as JSON strings containing:

• endpoint

• status

• message

HTML error pages are never returned directly.

Development

npm install
npm run build

prepublishOnly runs the build before publishing.