sonar-setup

Sonar Setup

Diagnose SonarQube MCP connectivity and guide the user through configuration.

Announce at start: "Checking SonarQube setup."

Process

Step 1: Check environment variables

Run a shell command to check which env vars are set (never print token values):

echo "SONARQUBE_URL: ${SONARQUBE_URL:-(not set)}"
echo "SONARQUBE_TOKEN: ${SONARQUBE_TOKEN:+set (hidden)}${SONARQUBE_TOKEN:-(not set)}"
echo "SONARQUBE_IDE_PORT: ${SONARQUBE_IDE_PORT:-(not set)}"

If SONARQUBE_URL or SONARQUBE_TOKEN are missing, guide the user:

Set these environment variables to connect:

export SONARQUBE_URL="https://your-sonarqube-instance"
export SONARQUBE_TOKEN="your-token"

Generate a token at <your-sonarqube>/account/security/.

Step 2: Check server reachability

If both URL and token are set, test connectivity:

curl -sf --connect-timeout 5 "${SONARQUBE_URL}/api/system/status" 2>/dev/null || echo "UNREACHABLE"

If unreachable, suggest common causes:

• VPN not connected (common for corporate SonarQube instances)
• Server URL is wrong
• Token expired or revoked

Step 3: Check MCP tool availability

Use ToolSearch to find SonarQube MCP tools by searching for sonarqube. The tools may be prefixed with mcp__sonarqube__ or mcp__sonar__ depending on the user's config. Check for search_sonar_issues_in_projects (standalone) and analyze_file_list (IDE-connected).

Report findings as a table:

Tool	Status	What it enables
search_sonar_issues_in_projects	Found / Not found	Issue browsing, fix, triage
get_project_quality_gate_status	Found / Not found	Quality gate checks
get_component_measures	Found / Not found	Dashboard metrics
analyze_file_list	Found / Not found	Local pre-push analysis

Step 4: Discover IDE ports

Scan the SonarQube for IDE port range to find all active instances:

for port in $(seq 64120 64130); do
  if curl -sf --connect-timeout 0.5 -o /dev/null "http://localhost:${port}" 2>/dev/null; then
    echo "SonarQube for IDE found on port ${port}"
  fi
done

Report all active ports — each one corresponds to a different IDE instance.

If a port is found but SONARQUBE_IDE_PORT is not set, guide the user:

SonarQube for IDE detected on port <port>. To enable local analysis, set the env var before starting Claude Code:

export SONARQUBE_IDE_PORT=<port>

The port may change when you restart your IDE. Re-run /code-quality:sonar-setup to find the new port.

If multiple ports are active, explain:

Multiple SonarQube for IDE instances detected (ports: <list>). Each corresponds to a different IDE. Set SONARQUBE_IDE_PORT to the one you want Claude Code to analyze with. You cannot switch mid-session — changing requires restarting Claude Code.

Step 5: Report detected mode

Summarize the overall setup status:

Full setup (IDE-connected):

SonarQube is fully configured. All code-quality skills are functional, including local pre-push analysis via sonar-verify.

Standalone mode:

SonarQube is connected in standalone mode. Remote skills work: sonar-status, sonar-issues, sonar-fix, sonar-triage, sonar-rule. Local analysis (sonar-verify) requires IDE-connected mode — see Step 4.

Not configured:

SonarQube MCP is not available. Code-quality skills will not work until the MCP server is configured.

If MCP tools are not found, show the config snippet:

// Add to your MCP configuration
// Standalone mode (remote analysis only):
{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_URL",
        "mcp/sonarqube"
      ]
    }
  }
}

// Full-power mode (adds local analysis):
{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_IDE_PORT",
        "mcp/sonarqube"
      ]
    }
  }
}

On Linux, add "--network=host" to the args array (before "mcp/sonarqube") so the Docker container can reach SonarQube for IDE on localhost.

References

For deeper documentation on tool schemas, bug guardrails, and operational patterns:

• references/sonarqube-mcp-tools.md — full tool catalogue with response schemas and call examples
• references/sonarqube-mcp-guide.md — modes, taxonomy, token management, metrics cheat sheet
• references/official-docs.md — links to SonarSource documentation and community discussions

Common Mistakes

Don't	Do
Print or log the SONARQUBE_TOKEN value	Only confirm it is set — never reveal
Assume the IDE port is always 64120	Scan the full range 64120-64130
Hardcode a SonarQube URL in the config snippet	Use env var pass-through so the config is project-agnostic
Skip the reachability check	Always verify — VPN/firewall issues are the most common problem
Tell the user to restart Claude Code for every port change	Suggest re-running /code-quality:sonar-setup to detect the new port, then restart only if needed
Forget the Linux --network=host flag	Docker on Linux cannot reach localhost without it — macOS/Windows work without it