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.

| Variable | Required | Description | | --- | --- | --- | | SONAR_HOST_URL | Yes | SonarQube base URL. Trailing slashes are normalized. | | SONAR_TOKEN | Yes | SonarQube token. Sent as Basic Auth using Authorization: Basic base64("${SONAR_TOKEN}:"). | | SONAR_PROJECT_KEY | No | Default project key used by project-scoped tools when projectKey and projectName are omitted. |

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.