MCP SonarCloud Server

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.

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