# SonarQube MCP Server

The SonarQube MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes SonarQube Server and SonarQube Cloud functionality as a set of tools consumable by AI agent clients such as Claude, Cursor, VS Code Copilot, GitHub Copilot, Windsurf, and others. It acts as a bridge between an LLM-powered coding assistant and a SonarQube instance, enabling the agent to search projects, inspect issues, analyze code snippets, review security hotspots, check quality gates, retrieve metrics, and manage webhooks — all through natural language prompts. The server is distributed as an OCI container image (`mcp/sonarqube`) that wraps a self-contained Java 21 JAR, and it supports three transport modes: stdio (default, recommended for local development), HTTP, and HTTPS (recommended for multi-user production deployments).

At its core the server registers a catalogue of MCP tools organized into named toolsets (`analysis`, `issues`, `projects`, `quality-gates`, `rules`, `security-hotspots`, `duplications`, `measures`, `coverage`, `sources`, `languages`, `portfolios`, `system`, `webhooks`, `dependency-risks`, `cag`). On startup it initializes a SonarLint backend in the background to download language analyzers, then immediately makes all REST-API-backed tools available without waiting for the download to complete. In stdio mode a single SonarQube token is read from the `SONARQUBE_TOKEN` environment variable and reused for all requests; in HTTP/HTTPS mode each request must supply its own `Authorization: Bearer <token>` header so the server remains fully stateless. The `SONARQUBE_TOOLSETS` environment variable (or the same-named HTTP request header) restricts which toolsets are exposed, and `SONARQUBE_READ_ONLY=true` hides all write operations globally or per-request.

---

## Configuration and Setup

### Stdio transport — Docker with SonarQube Cloud

The fastest way to add the server to an MCP client. The process is spawned as a child of the client; credentials are injected via environment variables.

```json
// Claude Desktop / Cursor / VS Code mcp.json
{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run", "--init", "--pull=always", "-i", "--rm",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<your-sonarqube-cloud-token>",
        "SONARQUBE_ORG":   "<your-org-key>"
      }
    }
  }
}
```

### Stdio transport — Docker with SonarQube Server

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run", "--init", "--pull=always", "-i", "--rm",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_URL",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<your-user-token>",
        "SONARQUBE_URL":   "https://sonarqube.example.com"
      }
    }
  }
}
```

### Stdio transport — Claude Code CLI

```bash
# SonarQube Cloud
claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  --env SONARQUBE_ORG=$SONAR_ORG \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG mcp/sonarqube

# SonarQube Server
claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  --env SONARQUBE_URL=$SONAR_URL \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL mcp/sonarqube
```

### HTTPS transport — multi-user production deployment

Each client supplies its own token in the `Authorization` header; no token is stored server-side between requests.

```bash
# Start server
docker run --init --pull=always -p 8443:8443 \
  -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  -e SONARQUBE_TRANSPORT=https \
  -e SONARQUBE_HTTP_PORT=8443 \
  -e SONARQUBE_ORG="my-org" \
  mcp/sonarqube
```

```json
// Client configuration
{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization":      "Bearer <your-token>",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY":"true"
      }
    }
  }
}
```

### Workspace mount — reduce context bloat for code analysis

When the project directory is mounted at `/app/mcp-workspace`, analysis tools read files directly from disk instead of requiring the agent to pass file contents.

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always", "--init",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-v", "/absolute/path/to/project:/app/mcp-workspace",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_TOKEN":       "<token>",
        "SONARQUBE_ORG":         "<org>",
        "SONARQUBE_PROJECT_KEY": "my-project"
      }
    }
  }
}
```

### Build from source

```bash
./gradlew clean build -x test
# Outputs: build/libs/sonarqube-mcp-server-<version>.jar

# Run locally (stdio mode)
java -jar build/libs/sonarqube-mcp-server-*.jar
# Required env vars: STORAGE_PATH, SONARQUBE_TOKEN, and SONARQUBE_ORG or SONARQUBE_URL
```

---

## Environment Variables Reference

| Variable | Required | Description |
|---|---|---|
| `STORAGE_PATH` | Yes | Absolute path to a writable directory for the server's internal files and logs |
| `SONARQUBE_TOKEN` | Yes (stdio) | SonarQube user token; omit in HTTP mode (provided per-request) |
| `SONARQUBE_ORG` | For SQC | SonarQube Cloud organization key; its presence selects Cloud over Server |
| `SONARQUBE_URL` | For SQS | SonarQube Server URL (e.g. `https://sonarqube.example.com`). Also `https://sonarqube.us` for SQC US |
| `SONARQUBE_PROJECT_KEY` | No | Default project key; removes `projectKey` from tool schemas when set |
| `SONARQUBE_TOOLSETS` | No | Comma-separated toolset keys to enable (default: `analysis,issues,projects,quality-gates,rules,duplications,measures,security-hotspots,dependency-risks,coverage,cag`) |
| `SONARQUBE_READ_ONLY` | No | `true` disables all write operations globally |
| `SONARQUBE_TRANSPORT` | No | `http` or `https` to enable network transport (default: stdio) |
| `SONARQUBE_HTTP_PORT` | No | HTTP/HTTPS port, 1024–65535 (default: `8080`) |
| `SONARQUBE_HTTP_HOST` | No | Bind address (default: `127.0.0.1`) |
| `SONARQUBE_HTTP_ALLOWED_ORIGINS` | No | Comma-separated additional allowed CORS origins |
| `SONARQUBE_IDE_PORT` | No | Port 64120–64130 to connect to SonarQube for IDE bridge |
| `SONARQUBE_DEBUG_ENABLED` | No | `true` enables debug logging to STDERR and log file |
| `SONARQUBE_LOG_TO_FILE_DISABLED` | No | `true` disables writing logs to disk |
| `TELEMETRY_DISABLED` | No | `true` disables anonymous usage telemetry |
| `SONARQUBE_HTTPS_KEYSTORE_PATH` | No | Path to keystore (default: `/etc/ssl/mcp/keystore.p12`) |
| `SONARQUBE_HTTPS_KEYSTORE_PASSWORD` | No | Keystore password (default: `sonarlint`) |
| `SONARQUBE_HTTPS_KEYSTORE_TYPE` | No | `PKCS12` or `JKS` (default: `PKCS12`) |

---

## Tool: `search_my_sonarqube_projects`

Finds SonarQube projects accessible to the authenticated user, returning their keys and names with pagination. Most other tools require a project key — use this tool first when the key is unknown.

```json
// MCP tool call
{
  "name": "search_my_sonarqube_projects",
  "arguments": {
    "q":        "payment",
    "pageSize": 10,
    "page":     1
  }
}

// Expected response
{
  "projects": [
    { "key": "com.example:payment-service", "name": "Payment Service" },
    { "key": "com.example:payment-ui",      "name": "Payment UI" }
  ],
  "paging": {
    "pageIndex": 1,
    "pageSize":  10,
    "total":     2,
    "hasNextPage": false
  }
}
```

---

## Tool: `search_sonar_issues_in_projects`

Searches for bugs, vulnerabilities, and code smells across one or more projects with rich filtering by severity, software quality, and status.

```json
// Find all open HIGH/BLOCKER security issues in two projects
{
  "name": "search_sonar_issues_in_projects",
  "arguments": {
    "projects":               ["com.example:payment-service", "com.example:auth-service"],
    "severities":             ["HIGH", "BLOCKER"],
    "impactSoftwareQualities":["SECURITY"],
    "issueStatuses":          ["OPEN"],
    "ps":                     50,
    "p":                      1
  }
}

// Expected response
{
  "issues": [
    {
      "key":                    "AX-HMISMFixnZED5FL23",
      "rule":                   "java:S2068",
      "project":                "com.example:payment-service",
      "component":              "com.example:payment-service:src/main/java/PaymentController.java",
      "severity":               "BLOCKER",
      "status":                 "OPEN",
      "message":                "Hard-coded password",
      "cleanCodeAttribute":     "TRUSTWORTHY",
      "cleanCodeAttributeCategory": "RESPONSIBLE",
      "author":                 "dev@example.com",
      "creationDate":           "2024-11-15T10:23:00+0000",
      "textRange":              { "startLine": 42, "endLine": 42 }
    }
  ],
  "paging": { "pageIndex": 1, "pageSize": 50, "total": 1 }
}
```

---

## Tool: `change_sonar_issue_status`

Changes the resolution status of a single SonarQube issue to `accept`, `falsepositive`, or re-opens it with `reopen`. Requires write access (disabled when `SONARQUBE_READ_ONLY=true`).

```json
// Accept a false-positive noise issue
{
  "name": "change_sonar_issue_status",
  "arguments": {
    "key":    "AX-HMISMFixnZED5FL23",
    "status": "falsepositive"
  }
}

// Expected response
{
  "success": true,
  "message": "The issue status was successfully changed.",
  "key":     "AX-HMISMFixnZED5FL23",
  "status":  "falsepositive"
}

// Reopen a previously accepted issue
{
  "name": "change_sonar_issue_status",
  "arguments": {
    "key":    "AX-HMISMFixnZED5FL23",
    "status": "reopen"
  }
}
```

---

## Tool: `analyze_code_snippet`

Analyzes a file or code snippet locally using the embedded SonarLint engine, applying the project's quality profile rules. Works in two modes: full-file (when no `codeSnippet` is given) or snippet-filtered (only reports issues intersecting the supplied snippet).

```json
// Mode 1: Analyze a full file by content (no workspace mount)
{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey":  "com.example:payment-service",
    "fileContent": "public class Foo {\n  String password = \"admin123\";\n  void login() { System.out.println(password); }\n}",
    "language":    "java",
    "scope":       "MAIN"
  }
}

// Mode 2: Analyze by file path (requires workspace mounted at /app/mcp-workspace)
{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey": "com.example:payment-service",
    "filePath":   "src/main/java/PaymentController.java",
    "language":   "java",
    "scope":      "MAIN"
  }
}

// Mode 3: Filter results to a specific snippet within the file
{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey":  "com.example:payment-service",
    "fileContent": "public class Foo {\n  String password = \"admin123\";\n  void login() {}\n}",
    "codeSnippet": "String password = \"admin123\";",
    "language":    "java",
    "scope":       "MAIN"
  }
}

// Expected response
{
  "issues": [
    {
      "ruleKey":           "java:S2068",
      "message":           "Hard-coded password",
      "severity":          "BLOCKER",
      "cleanCodeAttribute":"TRUSTWORTHY",
      "impacts":           "{SECURITY=HIGH}",
      "hasQuickFix":       false,
      "textRange":         { "startLine": 2, "endLine": 2 }
    }
  ],
  "issueCount": 1
}
```

---

## Tool: `run_advanced_code_analysis`

Runs server-side advanced analysis on a single file using SonarQube Cloud's full engine (cross-file taint analysis, etc.). Requires the workspace to be mounted and the organization to be entitled for advanced analysis.

```json
{
  "name": "run_advanced_code_analysis",
  "arguments": {
    "projectKey": "com.example:payment-service",
    "branchName": "main",
    "filePath":   "src/main/java/PaymentController.java",
    "fileScope":  "MAIN"
  }
}

// Expected response
{
  "issues": [
    {
      "id":       "issue-uuid-1234",
      "filePath": "src/main/java/PaymentController.java",
      "message":  "SQL injection via tainted input from line 15",
      "rule":     "java:S3649",
      "textRange":{ "startLine": 42, "endLine": 42 },
      "flows": [
        {
          "type":        "DATA_FLOW",
          "description": "Taint flow from user input to SQL query",
          "locations": [
            { "textRange": { "startLine": 15, "endLine": 15 }, "message": "Source: request.getParameter()", "file": "src/main/java/PaymentController.java" },
            { "textRange": { "startLine": 42, "endLine": 42 }, "message": "Sink: executeQuery()", "file": "src/main/java/PaymentController.java" }
          ]
        }
      ]
    }
  ],
  "patchResult": null,
  "analysisErrors": null
}
```

---

## Tool: `search_security_hotspots`

Searches for Security Hotspots (security-sensitive code locations requiring human review) in a project, with filtering by status, resolution, file, and new-code period.

```json
// Find all unreviewed hotspots in new code
{
  "name": "search_security_hotspots",
  "arguments": {
    "projectKey":       "com.example:payment-service",
    "status":           "TO_REVIEW",
    "sinceLeakPeriod":  true,
    "ps":               25
  }
}

// Retrieve specific hotspots by key
{
  "name": "search_security_hotspots",
  "arguments": {
    "hotspotKeys": ["AX-HSec1234", "AX-HSec5678"]
  }
}

// Expected response
{
  "hotspots": [
    {
      "key":                  "AX-HSec1234",
      "component":            "com.example:payment-service:src/main/java/CryptoUtil.java",
      "project":              "com.example:payment-service",
      "securityCategory":     "weak-cryptography",
      "vulnerabilityProbability": "HIGH",
      "status":               "TO_REVIEW",
      "resolution":           null,
      "line":                 87,
      "message":              "Use a secure random number generator",
      "author":               "dev@example.com",
      "creationDate":         "2024-12-01T08:00:00+0000",
      "ruleKey":              "java:S2245"
    }
  ],
  "paging": { "pageIndex": 1, "pageSize": 25, "total": 1 }
}
```

---

## Tool: `show_security_hotspot`

Returns full details of a single Security Hotspot including rule description, code context, data-flow locations, and review comments.

```json
{
  "name": "show_security_hotspot",
  "arguments": {
    "hotspotKey": "AX-HSec1234"
  }
}

// Expected response (abbreviated)
{
  "key":       "AX-HSec1234",
  "status":    "TO_REVIEW",
  "component": "com.example:payment-service:src/main/java/CryptoUtil.java",
  "rule": {
    "key":         "java:S2245",
    "name":        "Pseudorandom number generators should not be used in security context",
    "securityCategory": "weak-cryptography",
    "vulnerabilityProbability": "HIGH",
    "riskDescription": "Using weak RNG in security-sensitive operations..."
  }
}
```

---

## Tool: `change_security_hotspot_status`

Reviews a Security Hotspot by changing its status to `TO_REVIEW` or `REVIEWED`. When marking as `REVIEWED`, one of three resolutions must be specified: `FIXED`, `SAFE`, or `ACKNOWLEDGED`.

```json
// Mark as safe after review
{
  "name": "change_security_hotspot_status",
  "arguments": {
    "hotspotKey": "AX-HSec1234",
    "status":     "REVIEWED",
    "resolution": "SAFE",
    "comment":    "Reviewed: uses java.security.SecureRandom in production path, only falls back to Math.random in tests"
  }
}

// Acknowledge as accepted risk
{
  "name": "change_security_hotspot_status",
  "arguments": {
    "hotspotKey": "AX-HSec5678",
    "status":     "REVIEWED",
    "resolution": "ACKNOWLEDGED"
  }
}

// Expected response
{
  "success":    true,
  "message":    "The Security Hotspot status was successfully changed.",
  "hotspotKey": "AX-HSec1234",
  "status":     "REVIEWED",
  "resolution": "SAFE"
}
```

---

## Tool: `get_project_quality_gate_status`

Returns the Quality Gate status for a project, branch, or pull request, including the pass/fail condition breakdown per metric.

```json
// Check quality gate by project key
{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey": "com.example:payment-service"
  }
}

// Check quality gate for a pull request
{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey":  "com.example:payment-service",
    "pullRequest": "247"
  }
}

// Expected response
{
  "status": "ERROR",
  "conditions": [
    {
      "metricKey":      "new_coverage",
      "status":         "ERROR",
      "errorThreshold": "80",
      "actualValue":    "62.5"
    },
    {
      "metricKey":      "new_blocker_violations",
      "status":         "OK",
      "errorThreshold": "0",
      "actualValue":    "0"
    }
  ]
}
```

---

## Tool: `list_quality_gates`

Lists all Quality Gates configured in the SonarQube instance or organization.

```json
{
  "name": "list_quality_gates",
  "arguments": {}
}

// Expected response
{
  "qualitygates": [
    { "id": "1", "name": "Sonar way",   "isDefault": true,  "isBuiltIn": true  },
    { "id": "5", "name": "Strict gate", "isDefault": false, "isBuiltIn": false }
  ]
}
```

---

## Tool: `get_component_measures`

Retrieves metric values (coverage, complexity, lines of code, violations, etc.) for a project or component.

```json
{
  "name": "get_component_measures",
  "arguments": {
    "projectKey": "com.example:payment-service",
    "metricKeys": ["ncloc", "coverage", "complexity", "violations", "sqale_index"]
  }
}

// Expected response
{
  "component": {
    "key":       "com.example:payment-service",
    "name":      "Payment Service",
    "qualifier": "TRK"
  },
  "measures": [
    { "metric": "ncloc",       "value": "12450" },
    { "metric": "coverage",    "value": "74.3"  },
    { "metric": "complexity",  "value": "934"   },
    { "metric": "violations",  "value": "12"    },
    { "metric": "sqale_index", "value": "480"   }
  ]
}
```

---

## Tool: `search_files_by_coverage`

Lists files in a project sorted by coverage ascending (worst coverage first), with optional threshold filtering and pagination.

```json
// Files with less than 50% coverage
{
  "name": "search_files_by_coverage",
  "arguments": {
    "projectKey":  "com.example:payment-service",
    "maxCoverage": 50,
    "pageSize":    20,
    "pageIndex":   1
  }
}

// Expected response
{
  "projectKey":      "com.example:payment-service",
  "totalFiles":      145,
  "filteredFiles":   8,
  "pageIndex":       1,
  "pageSize":        20,
  "projectSummary":  { "coverage": 74.3, "linesToCover": 9800, "uncoveredLines": 2519 },
  "files": [
    {
      "key":               "com.example:payment-service:src/main/java/LegacyBatch.java",
      "path":              "src/main/java/LegacyBatch.java",
      "coverage":          12.5,
      "lineCoverage":      10.0,
      "branchCoverage":    15.0,
      "linesToCover":      200,
      "uncoveredLines":    175
    }
  ]
}
```

---

## Tool: `get_file_coverage_details`

Returns line-by-line coverage detail for a specific file, identifying exactly which lines and branches are uncovered.

```json
{
  "name": "get_file_coverage_details",
  "arguments": {
    "key":  "com.example:payment-service:src/main/java/LegacyBatch.java",
    "from": 1,
    "to":   50
  }
}

// Expected response (abbreviated)
{
  "key": "com.example:payment-service:src/main/java/LegacyBatch.java",
  "lines": [
    { "line": 10, "covered": true,  "branches": 2, "coveredBranches": 2 },
    { "line": 15, "covered": false, "branches": 0, "coveredBranches": 0 },
    { "line": 20, "covered": true,  "branches": 4, "coveredBranches": 1 }
  ]
}
```

---

## Tool: `search_duplicated_files`

Finds all files with code duplications in a project. By default auto-fetches all pages (up to 10 000 files); supports manual pagination.

```json
// Auto-fetch all duplicated files (default mode)
{
  "name": "search_duplicated_files",
  "arguments": {
    "projectKey": "com.example:payment-service"
  }
}

// Manual pagination
{
  "name": "search_duplicated_files",
  "arguments": {
    "projectKey": "com.example:payment-service",
    "pageSize":   100,
    "pageIndex":  1
  }
}

// Expected response
{
  "duplicatedFiles": [
    {
      "key":                  "com.example:payment-service:src/main/java/Utils.java",
      "name":                 "Utils.java",
      "path":                 "src/main/java/Utils.java",
      "duplicatedLines":      45,
      "duplicatedBlocks":     3,
      "duplicatedLinesDensity": "8.2"
    }
  ],
  "paging":  { "pageIndex": 1, "pageSize": 1, "total": 1 },
  "summary": { "totalDuplicatedLines": 45, "totalDuplicatedBlocks": 3, "overallDensity": "8.2" }
}
```

---

## Tool: `get_duplications`

Returns the specific duplicated blocks and their locations for a single file.

```json
{
  "name": "get_duplications",
  "arguments": {
    "key": "com.example:payment-service:src/main/java/Utils.java"
  }
}

// Expected response
{
  "duplications": [
    {
      "blocks": [
        { "from": 10, "size": 15, "ref": "1" },
        { "from": 55, "size": 15, "ref": "2" }
      ]
    }
  ],
  "files": {
    "1": { "key": "com.example:payment-service:src/main/java/Utils.java",   "name": "Utils.java" },
    "2": { "key": "com.example:payment-service:src/main/java/OldUtils.java", "name": "OldUtils.java" }
  }
}
```

---

## Tool: `show_rule`

Returns complete rule metadata including name, severity, type, language, description sections, and software quality impacts.

```json
{
  "name": "show_rule",
  "arguments": {
    "key": "java:S2068"
  }
}

// Expected response
{
  "key":      "java:S2068",
  "name":     "Hard-coded passwords are security-sensitive",
  "severity": "CRITICAL",
  "type":     "VULNERABILITY",
  "lang":     "java",
  "langName": "Java",
  "impacts": [
    { "softwareQuality": "SECURITY", "severity": "HIGH" }
  ],
  "descriptionSections": [
    { "content": "<p>Hardcoding passwords is security-sensitive...</p>" }
  ]
}
```

---

## Tool: `get_raw_source`

Retrieves the raw source code of a file stored in SonarQube. Requires the "See Source Code" permission on the project.

```json
{
  "name": "get_raw_source",
  "arguments": {
    "key": "com.example:payment-service:src/main/java/PaymentController.java"
  }
}

// With pull request context
{
  "name": "get_raw_source",
  "arguments": {
    "key":         "com.example:payment-service:src/main/java/PaymentController.java",
    "pullRequest": "247"
  }
}

// Expected response
{
  "key":    "com.example:payment-service:src/main/java/PaymentController.java",
  "source": "package com.example;\n\npublic class PaymentController {\n  // ...\n}\n"
}
```

---

## Tool: `get_scm_info`

Returns SCM (version control) information for each line of a file: commit ID, author, and date.

```json
{
  "name": "get_scm_info",
  "arguments": {
    "key":             "com.example:payment-service:src/main/java/PaymentController.java",
    "commits_by_line": "true",
    "from":            1,
    "to":              10
  }
}

// Expected response (abbreviated)
{
  "scm": [
    [1, "a3f2bc1", "alice@example.com", "2024-11-10"],
    [2, "a3f2bc1", "alice@example.com", "2024-11-10"],
    [5, "ff7d2e9", "bob@example.com",   "2024-12-01"]
  ]
}
```

---

## Tool: `search_dependency_risks`

Searches for SCA (Software Composition Analysis) dependency vulnerabilities in a project. Requires SonarQube Server 2025.4 Enterprise+ with Advanced Security, or SonarQube Cloud with Advanced Security enabled.

```json
{
  "name": "search_dependency_risks",
  "arguments": {
    "projectKey": "com.example:payment-service",
    "branchKey":  "main"
  }
}

// Expected response
{
  "issuesReleases": [
    {
      "key":             "DPR-001",
      "severity":        "HIGH",
      "type":            "VULNERABILITY",
      "quality":         "SECURITY",
      "status":          "OPEN",
      "createdAt":       "2024-10-15T00:00:00Z",
      "vulnerabilityId": "CVE-2024-12345",
      "cvssScore":       9.1,
      "release": {
        "packageName":    "org.apache.commons:commons-text",
        "version":        "1.9",
        "packageManager": "maven",
        "newlyIntroduced": false
      },
      "assignee": null
    }
  ]
}
```

---

## Tool: `list_pull_requests`

Lists all pull requests for a project, returning the keys needed for other tools that accept a pull request context.

```json
{
  "name": "list_pull_requests",
  "arguments": {
    "projectKey": "com.example:payment-service"
  }
}

// Expected response
{
  "pullRequests": [
    {
      "key":    "247",
      "title":  "Add payment retry logic",
      "branch": "feature/payment-retry",
      "base":   "main",
      "status": { "qualityGateStatus": "ERROR" },
      "analysisDate": "2024-12-10T14:22:00+0000"
    }
  ]
}
```

---

## Tool: `search_metrics`

Lists all metrics available in the SonarQube instance (e.g. `ncloc`, `coverage`, `sqale_index`) with their types and domains.

```json
{
  "name": "search_metrics",
  "arguments": {
    "p":  1,
    "ps": 20
  }
}

// Expected response
{
  "metrics": [
    { "key": "ncloc",       "name": "Lines of Code",  "type": "INT",     "domain": "Size"       },
    { "key": "coverage",    "name": "Coverage",        "type": "PERCENT", "domain": "Coverage"   },
    { "key": "sqale_index", "name": "Technical Debt",  "type": "WORK_DUR","domain": "Maintainability" }
  ],
  "paging": { "pageIndex": 1, "pageSize": 20, "total": 87 }
}
```

---

## Tool: `list_languages`

Lists all programming languages supported and configured in the SonarQube instance.

```json
{
  "name": "list_languages",
  "arguments": { "q": "java" }
}

// Expected response
{
  "languages": [
    { "key": "java",    "name": "Java"       },
    { "key": "kotlin",  "name": "Kotlin"     },
    { "key": "groovy",  "name": "Groovy"     }
  ]
}
```

---

## Tool: `create_webhook`

Creates a new webhook that fires on SonarQube analysis events. Requires Administer permission. An optional HMAC secret can be configured for payload verification.

```json
{
  "name": "create_webhook",
  "arguments": {
    "name":       "CI Notification",
    "url":        "https://ci.example.com/sonar-webhook",
    "projectKey": "com.example:payment-service",
    "secret":     "my-hmac-secret-32chars-minimum!!"
  }
}

// Expected response
{
  "key":       "webhook-uuid-1234",
  "name":      "CI Notification",
  "url":       "https://ci.example.com/sonar-webhook",
  "hasSecret": true
}
```

---

## Tool: `list_webhooks`

Lists existing webhooks for an organization or specific project.

```json
{
  "name": "list_webhooks",
  "arguments": {
    "projectKey": "com.example:payment-service"
  }
}

// Expected response
{
  "webhooks": [
    {
      "key":        "webhook-uuid-1234",
      "name":       "CI Notification",
      "url":        "https://ci.example.com/sonar-webhook",
      "hasSecret":  true,
      "latestDelivery": {
        "id":         "delivery-uuid-5678",
        "at":         "2024-12-10T14:25:00+0000",
        "success":    true,
        "httpStatus": 200,
        "duration":   45
      }
    }
  ]
}
```

---

## Tool: `get_system_health` (SonarQube Server only)

Returns the health status of a SonarQube Server instance.

```json
{
  "name": "get_system_health",
  "arguments": {}
}

// Expected response
{
  "health": "GREEN",
  "causes": []
}
// Possible values: GREEN (fully operational), YELLOW (usable, needs attention), RED (not operational)
```

---

## Tool: `get_system_status` (SonarQube Server only)

Returns the current lifecycle state and version of the SonarQube Server.

```json
{
  "name": "get_system_status",
  "arguments": {}
}

// Expected response
{
  "id":      "server-uuid",
  "version": "2025.1.0.1234",
  "status":  "UP"
}
// Possible statuses: STARTING, UP, DOWN, RESTARTING, DB_MIGRATION_NEEDED, DB_MIGRATION_RUNNING
```

---

## Tool: `ping_system` (SonarQube Server only)

Lightweight liveness check that returns `"pong"` when the server is reachable.

```json
{
  "name": "ping_system",
  "arguments": {}
}

// Expected response
{ "pong": "pong" }
```

---

## Tool: `get_system_logs` (SonarQube Server only)

Retrieves SonarQube Server log files. Requires system administration permission.

```json
{
  "name": "get_system_logs",
  "arguments": {
    "name": "web"
  }
}
// Valid log names: access, app (default), ce, deprecation, es, web
```

---

## Tool: `list_portfolios`

Lists portfolios. On SonarQube Cloud, an enterprise ID or `favorite=true` is required. On SonarQube Server, optional search and pagination are supported.

```json
// SonarQube Cloud
{
  "name": "list_portfolios",
  "arguments": {
    "enterpriseId": "enterprise-uuid",
    "q":            "backend",
    "pageSize":     10
  }
}

// SonarQube Server
{
  "name": "list_portfolios",
  "arguments": {
    "q":         "backend",
    "favorite":  true,
    "pageSize":  20,
    "pageIndex": 1
  }
}
```

---

## Tool: `list_enterprises` (SonarQube Cloud only)

Lists enterprises accessible to the authenticated user on SonarQube Cloud.

```json
{
  "name": "list_enterprises",
  "arguments": {
    "enterpriseKey": "my-enterprise"
  }
}

// Expected response
{
  "enterprises": [
    { "key": "my-enterprise", "name": "My Enterprise", "id": "enterprise-uuid" }
  ]
}
```

---

## Service Endpoints (HTTP/HTTPS mode)

When running in HTTP or HTTPS transport mode, two unauthenticated service endpoints are exposed in addition to `/mcp`. These do not require an `Authorization` header.

```bash
# Health probe — returns HTTP 200 with empty body when server is ready
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/health
# Output: 200

# Version info — returns JSON with deployed server version
curl -s http://localhost:8080/info
# Output: {"version":"1.17.0"}
```

---

## Proxied MCP Servers

The SonarQube MCP Server can proxy additional MCP servers bundled in the JAR at `src/main/resources/proxied-mcp-servers.json`. Proxied server tools are exposed alongside built-in tools under their original names.

```json
// proxied-mcp-servers.json
[
  {
    "name":    "context-augmentation",
    "command": "sonar-context-augmentation",
    "args":    [],
    "env":     {},
    "inherits": ["SONARQUBE_TOKEN", "SONARQUBE_ORG", "SONARQUBE_PROJECT_KEY"],
    "supportedTransports": ["stdio"],
    "instructions": "Use architecture tools to understand cross-file dependencies before suggesting refactors."
  }
]
```

```
// Startup log output showing proxied server discovery
INFO: Initializing 1 proxied MCP server(s)...
INFO: Connected to 'context-augmentation' - discovered 8 tool(s)
INFO: Loaded 8 proxied tool(s) from 1/1 server(s)
```

---

## Summary

The SonarQube MCP Server is purpose-built for AI-driven developer workflows: an agent can discover projects with `search_my_sonarqube_projects`, surface critical open issues with `search_sonar_issues_in_projects`, analyze a file before committing with `analyze_code_snippet` or `run_advanced_code_analysis`, review the quality gate result before merging with `get_project_quality_gate_status`, and triage security hotspots with `search_security_hotspots` / `change_security_hotspot_status` — all without leaving the agent context. The `search_files_by_coverage` and `get_file_coverage_details` tools enable coverage-improvement workflows, while `search_duplicated_files` and `get_duplications` support technical-debt reduction. The `show_rule` and `search_metrics` tools provide the metadata needed to explain findings to users in plain language.

For integration, the recommended pattern for individual developers is stdio transport with `SONARQUBE_PROJECT_KEY` set to avoid passing the project key on every call. For shared CI/gateway deployments, HTTPS transport with per-request `Authorization: Bearer` headers and optional per-request `SONARQUBE_TOOLSETS` / `SONARQUBE_READ_ONLY` headers provides fine-grained per-client access control without requiring separate server instances. The workspace mount (`-v /project:/app/mcp-workspace`) is strongly recommended for analysis tools: it keeps large file contents out of the agent's context window and unlocks `run_advanced_code_analysis`. Custom certificate bundles, SOCKS5 proxy support, and the `SONARQUBE_IDE_PORT` bridge to SonarQube for IDE further extend the integration surface for enterprise environments.