Skip to main content
Glama
mcp-sonarcloud
by lukleh

MCP SonarCloud Server

License: MIT Python 3.11+ MCP

A Model Context Protocol (MCP) server implementation for SonarCloud, providing tools to interact with SonarCloud projects, issues, quality gates, and security hotspots.

Default layout:

  • Config: ~/.config/lukleh/mcp-sonarcloud/config.toml

  • Credentials: injected via the MCP client or shell environment

  • State: ~/.local/state/lukleh/mcp-sonarcloud/

  • Cache: ~/.cache/lukleh/mcp-sonarcloud/

Features

This MCP server provides 15 comprehensive tools with detailed parameter documentation and examples:

Project Management (3 tools)

  • search_my_sonarqube_projects: List all SonarCloud projects in your organization with pagination

  • show_component: Get detailed metadata for a specific project or component

  • component_tree: Traverse the file/directory structure of a project

Issues (4 tools)

  • search_sonar_issues_in_projects: Search for issues with filtering by pull request, severity (INFO, LOW, MEDIUM, HIGH, BLOCKER), and more

  • list_issue_authors: Discover SCM authors who contributed to issues

  • get_issue_changelog: Retrieve the change history of an issue

  • list_issue_tags: List available tags used on issues

Quality Gates (5 tools)

  • get_project_quality_gate_status: Get the quality gate status (OK, ERROR, WARN, NONE) for a project, branch, or pull request

  • list_quality_gates: List all quality gates in your organization

  • show_quality_gate: Get detailed conditions for a specific quality gate

  • search_quality_gates: Find projects associated with a quality gate

  • get_quality_gate_by_project: Get the quality gate assigned to a project

Security Hotspots (3 tools)

  • search_hotspots: Search for security hotspots in a project with file, branch, or PR filters

  • show_hotspot: Get detailed information about a specific hotspot

  • change_hotspot_status: Change the status of a hotspot (TO_REVIEW or REVIEWED with resolution: FIXED, SAFE, ACKNOWLEDGED)

All tools include comprehensive parameter descriptions, valid value documentation, and usage examples for optimal AI agent integration.

Related MCP server: SonarQube MCP Server

Prerequisites

  • Python 3.11 or higher

  • uv package manager

  • A SonarCloud account with an API token

  • Claude Code or Codex AI client

Quick Start

1. Get Your SonarCloud Token

  1. Log in to SonarCloud

  2. Click on your avatar → My Account → Security

  3. Under "Generate Tokens", enter a name (e.g., "MCP Server")

  4. Click Generate

  5. Copy and save the token - you won't be able to see it again!

2. Find Your Organization Key

  1. Go to your organization on SonarCloud

  2. Look at the URL: https://sonarcloud.io/organizations/YOUR-ORG-KEY

  3. The YOUR-ORG-KEY part is your organization key

3. Install the Server

# Run the published package without cloning the repository
uvx mcp-sonarcloud@latest --write-sample-config

# Or install it once and reuse the command directly
uv tool install mcp-sonarcloud@latest
mcp-sonarcloud --write-sample-config

4. Create the Config File

The command above writes a starter config to ~/.config/lukleh/mcp-sonarcloud/config.toml. You can confirm the resolved runtime locations at any time:

uvx mcp-sonarcloud@latest --print-paths

Edit ~/.config/lukleh/mcp-sonarcloud/config.toml:

base_url = "https://sonarcloud.io"
organization = "your-org-key"
timeout_sec = 30

5. Set the Token Environment Variable

Set SONARCLOUD_TOKEN in the environment used to launch the server. For local shell testing, you can export it directly:

export SONARCLOUD_TOKEN=your-token-here

6. Configure Your AI Client

Claude Code:

claude mcp add sonarcloud \
  --scope {local, user, or project} \
  -e SONARCLOUD_TOKEN=your-token-here \
  -- uvx mcp-sonarcloud@latest

Codex:

codex mcp add sonarcloud \
  --env SONARCLOUD_TOKEN=your-token-here \
  -- uvx mcp-sonarcloud@latest

Important: Replace your-token-here with your real SonarCloud token.

7. Restart and Test

  1. Restart your AI client

  2. Try asking: "Can you list my SonarCloud projects?"

Configuration

Files

  • config.toml

    • base_url (optional): SonarCloud or SonarQube base URL

    • organization (optional): SonarCloud organization key

    • timeout_sec (optional): HTTP timeout in seconds

Environment Overrides

Environment variables are the source of secrets and also override file values when present:

  • SONARCLOUD_TOKEN

  • SONARCLOUD_ORGANIZATION

  • SONARCLOUD_URL

  • SONARCLOUD_TIMEOUT_SEC

Command Line Testing

You can test the server directly:

# Show the resolved runtime paths
uvx mcp-sonarcloud@latest --print-paths

# Write or refresh the default config file
uvx mcp-sonarcloud@latest --write-sample-config
uvx mcp-sonarcloud@latest --write-sample-config --overwrite

# Export the token for local testing
export SONARCLOUD_TOKEN=your-token-here

# Run the server with the default home-directory config
uvx mcp-sonarcloud@latest

# Or point at a different config root
uvx mcp-sonarcloud@latest --config-dir /path/to/config-dir

Local Development

If you want to work on the repository itself:

git clone https://github.com/lukleh/mcp-sonarcloud.git
cd mcp-sonarcloud
uv sync --extra dev
uv run pytest -q
uv run mcp-sonarcloud --print-paths

Usage Examples

Natural Language Queries

Once configured, you can ask your AI client:

  1. List projects: "Show me all my SonarCloud projects"

  2. Check quality gate: "What's the quality gate status for project X on PR 123?"

  3. Search hotspots: "Find all security hotspots in project X"

  4. Get hotspot details: "Show me details for hotspot AY1234567890"

  5. Update hotspot: "Mark hotspot AY1234567890 as reviewed and safe"

  6. Search issues: "Find all blocker issues in project X's pull request 123"

Tool Examples (Python)

List Projects

# Get first page of projects
search_my_sonarqube_projects(page="1")

Search Issues in Pull Request

# Search for issues in a specific pull request
search_sonar_issues_in_projects(
    projects=["my-project"],
    pullRequestId="123",
    ps=100
)

Check Quality Gate Status

# Get quality gate status for a pull request
get_project_quality_gate_status(
    projectKey="my-project",
    pullRequest="123"
)

Search Security Hotspots

# Search hotspots in a project
search_hotspots(
    projectKey="my-project",
    pullRequest="123"
)

# Search hotspots in a specific file
search_hotspots(
    projectKey="my-project",
    files="src/main/java/com/example/MyClass.java",
    branch="main"
)

Get Hotspot Details

# Get detailed information about a hotspot
show_hotspot(hotspot="AX1234567890")

Change Hotspot Status

# Mark a hotspot as reviewed and safe
change_hotspot_status(
    hotspot="AX1234567890",
    status="REVIEWED",
    resolution="SAFE"
)

# Mark a hotspot for review
change_hotspot_status(
    hotspot="AX1234567890",
    status="TO_REVIEW"
)

Valid status values:

  • TO_REVIEW: Mark for review

  • REVIEWED: Mark as reviewed (requires resolution)

Valid resolution values (when status=REVIEWED):

  • FIXED: The vulnerability has been fixed

  • SAFE: The code is safe and not a vulnerability

  • ACKNOWLEDGED: The risk is acknowledged but accepted

Troubleshooting

Common Issues

"Config file already exists"

  • --write-sample-config will not replace an existing file unless you add --overwrite

  • Use uvx mcp-sonarcloud@latest --print-paths to confirm which config path is active

"SONARCLOUD_TOKEN environment variable is required"

  • Double-check your token is correctly set in the environment variables

  • Verify there are no extra spaces or quotes around the token

"401 Unauthorized"

  • Your token might be invalid or expired

  • Generate a new token from SonarCloud and update your configuration

MCP server not available

  • Verify the server was added: claude mcp list or codex mcp list

  • Run uvx mcp-sonarcloud@latest --print-paths in your shell to confirm the package starts cleanly

  • Try removing and re-adding the server

  • Check your AI client logs for errors

API Endpoints Used

This server uses the following SonarCloud API endpoints:

Components / Projects

  • GET /api/components/search - List projects

  • GET /api/components/show - Show component metadata

  • GET /api/components/tree - Traverse component hierarchy

Issues

  • GET /api/issues/search - Search issues

  • GET /api/issues/authors - List issue authors

  • GET /api/issues/changelog - Get issue change history

  • GET /api/issues/tags - List issue tags

Quality Gates

  • GET /api/qualitygates/project_status - Get quality gate status

  • GET /api/qualitygates/list - List quality gates

  • GET /api/qualitygates/show - Show quality gate details

  • GET /api/qualitygates/search - Search projects by quality gate

  • GET /api/qualitygates/get_by_project - Get quality gate for project

Security Hotspots

  • GET /api/hotspots/search - Search security hotspots

  • GET /api/hotspots/show - Show hotspot details

  • POST /api/hotspots/change_status - Change hotspot status

For complete API documentation, see SONARCLOUD_API_SUPPORT.md.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Releasing

Maintainer release instructions live in RELEASING.md.

License

MIT License - see LICENSE file for details

Available Tools

15 tools
change_hotspot_statusA

Mark a hotspot TO_REVIEW or REVIEWED (with resolution) so downstream analyses see the new state.

This updates the status of a security hotspot after manual review.

Status values:

  • TO_REVIEW: Mark the hotspot as needing review (no resolution required)

  • REVIEWED: Mark as reviewed (resolution parameter is REQUIRED)

Resolution values (required when status=REVIEWED):

  • FIXED: The vulnerability has been fixed

  • SAFE: The code is safe and not actually a vulnerability

  • ACKNOWLEDGED: The risk is acknowledged but accepted

Examples:

  • Mark as reviewed and safe: change_hotspot_status(hotspot="AX123", status="REVIEWED", resolution="SAFE")

  • Mark for review: change_hotspot_status(hotspot="AX123", status="TO_REVIEW")

Inputs: status (required), hotspot (required), resolution. Returns: object

component_treeA

Traverse modules/files inside a project; supports paging, qualifier filters, and branch/PR context.

Returns a hierarchical view of project components (directories, files, modules). Use this to explore project structure or find specific files.

Example: component_tree(component="my-project", qualifiers=["FIL"], q="test", branch="main")

Inputs: component (required), p, q, ps, +6 more. Returns: object

get_issue_changelogA

Return the change history (status, assignee, severity edits) for the given issue key.

Returns a chronological list of all changes made to an issue, including who made the change and when. Useful for auditing issue lifecycle or understanding how an issue was resolved.

Example: get_issue_changelog(issue="AXabc123def456")

Inputs: issue (required). Returns: object

get_project_quality_gate_statusA

Check whether a project/branch/PR passed its assigned quality gate and inspect failing conditions.

Returns the quality gate status (OK, ERROR, WARN, NONE) and details of any failing conditions. At least one of analysisId, projectId, or projectKey must be provided.

Quality gate status values:

  • OK: All conditions passed

  • ERROR: One or more conditions failed

  • WARN: Warning threshold exceeded (deprecated)

  • NONE: No quality gate set

Example: get_project_quality_gate_status(projectKey="my-project", pullRequest="123")

Inputs: branch, projectId, analysisId, projectKey, +1 more. Returns: Quality gate status.

get_quality_gate_by_projectA

Return the gate currently bound to a project so workflows can cross-reference status and rules.

Returns information about which quality gate is assigned to the specified project. Use this to determine what quality criteria a project must meet. Requires SONARCLOUD_ORGANIZATION to be set.

Example: get_quality_gate_by_project(project="my-project")

Inputs: project (required). Returns: object

list_issue_authorsA

Discover SCM author accounts used in your org/project; useful for reviewer pickers or stats.

Returns a list of authors (from source control) who have contributed to issues in the organization or project. Requires SONARCLOUD_ORGANIZATION to be set.

Example: list_issue_authors(project="my-project", q="john")

Inputs: q, ps, project. Returns: object

list_issue_tagsA

List available issue tags (optionally filtered by project or search query) to power tag selectors.

Returns a list of tags used on issues in the organization or project. Tags are custom labels that can be applied to issues for categorization.

Example: list_issue_tags(project="my-project", q="security")

Inputs: q, ps, project. Returns: object

list_quality_gatesA

Enumerate all gates in the organization along with basic metadata and built-in flags.

Returns a list of all quality gates available in the organization, including their ID, name, and whether they are built-in or custom. Requires SONARCLOUD_ORGANIZATION to be set.

Example: list_quality_gates()

Inputs: no named parameters. Returns: object

search_hotspotsA

List hotspots for a project with optional file, branch, or PR filters; returns paging + summaries.

Security hotspots are security-sensitive pieces of code that need manual review. Returns a list of hotspots with their status, component, and vulnerability probability.

Hotspot status values:

  • TO_REVIEW: Needs review

  • REVIEWED: Has been reviewed (with resolution FIXED, SAFE, or ACKNOWLEDGED)

Example: search_hotspots(projectKey="my-project", branch="main", files="src/auth.java")

Inputs: projectKey (required), p, ps, files, +2 more. Returns: object

search_my_sonarqube_projectsA

Paginated project finder; use when you need keys/names before running other SonarCloud tools.

Returns a list of projects with their keys and names, plus pagination information. Use the project keys returned here for other tools like search_sonar_issues_in_projects or search_hotspots.

Example: search_my_sonarqube_projects(page="1")

Inputs: page. Returns: Response from search_my_sonarqube_projects tool.

search_quality_gatesA

Page through projects associated with a gate; supports filtering by selection status and name.

Returns a list of projects and their association status with the specified quality gate. Useful for understanding which projects use which quality gates. Requires SONARCLOUD_ORGANIZATION to be set.

Example: search_quality_gates(gateId=123, selected=True, query="my-project")

Inputs: gateId (required), page, query, pageSize, +1 more. Returns: object

search_sonar_issues_in_projectsA

Search issues across one or more projects with optional PR, severity, and pagination controls.

Returns a list of issues matching the filters, with key details like rule, severity, component, and status. Use this to find code quality issues, bugs, vulnerabilities, or code smells in your projects.

Example: search_sonar_issues_in_projects(projects=["my-project"], severities="HIGH,BLOCKER", pullRequestId="123")

Inputs: p, ps, projects, severities, +1 more. Returns: Response from search_sonar_issues_in_projects tool.

show_componentA

Return detailed metadata (qualifier, tags, branches) for a specific project/component.

Returns component information including name, qualifier (TRK for project, FIL for file, etc.), tags, and available branches. Use this to inspect project metadata or verify component existence.

Example: show_component(component="my-project", branch="main")

Inputs: component (required), branch, pullRequest. Returns: object

show_hotspotA

Return the full hotspot payload (rule, component, author, status) for a specific key.

Returns detailed information about a security hotspot, including the security rule that triggered it, the affected component/file, current status, resolution (if reviewed), and whether you can change its status.

Example: show_hotspot(hotspot="AXabc123def456")

Inputs: hotspot (required). Returns: Detailed security hotspot information.

show_quality_gateA

Fetch full gate definition (conditions, allowed actions) so LLMs can explain or compare them.

Returns detailed information about a specific quality gate, including all conditions (coverage thresholds, bug counts, etc.) and metadata. Requires SONARCLOUD_ORGANIZATION to be set. Either name or gate_id must be provided.

Example: show_quality_gate(name="Sonar way")

Inputs: name, gate_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: issues (search, changelog, authors, tags), hotspots (search, show, change status), quality gates (list, show, search, get by project, get status), and components (show, tree). Even the multiple quality-gate tools are clearly separated by purpose (listing all, showing one, associating projects, fetching by project, checking status). No two tools appear to do the same thing.

    Naming Consistency4/5

    Tool names predominantly follow a verb_noun pattern: get_, list_, search_, show_, change_. The main deviation is 'component_tree' (noun_noun) instead of something like 'get_component_tree'. Also 'search_my_sonarqube_projects' uses an awkward 'my' qualifier. Overall, the naming is predictable and readable, with only minor inconsistencies.

    Tool Count5/5

    15 tools is at the upper end of the ideal 3-15 range but well-scoped for a SonarCloud server covering projects, issues, hotspots, and quality gates. Each tool serves a distinct need, and none feel redundant or superfluous. The count is appropriate for the breadth of the domain.

    Completeness4/5

    The toolset provides good read coverage for projects, components, issues, hotspots, and quality gates, plus write capability for hotspot status changes. Minor gaps include the absence of an update-issue tool (e.g., to resolve or reassign issues) and no create/modify/delete operations for quality gates or projects. These are workable gaps since the server seems focused on analysis and reporting, but agents may need to work around the missing issue-update capability.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables access to Codacy's code quality platform through natural language, providing repository management, security analysis, pull request reviews, and local CLI-based code analysis. Supports comprehensive code quality monitoring including issues, coverage, security vulnerabilities, and technical debt assessment across organizations and repositories.
      2,176 npm
      58
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying and managing Sentry projects, issues, and events through natural language.
      9 npm
      ISC