Introduction
Sound familiar? You finish writing some code, open a PR, and then CI blows up with a wall of static analysis findings. You spend the next hour tracking down issues that, honestly, you could have caught at the keyboard.
SonarQube is one of the most widely adopted code quality platforms in the industry. It detects bugs, vulnerabilities, code smells, and security hotspots, and tracks coverage and duplication. Now it can be integrated directly into Claude Code — so the same AI session that helps you write code can also scan it, flag problems, and fix them on the spot.
This article is a complete walkthrough: from first install to day-to-day usage. But before we get into the steps, there is one critical gotcha you need to know about first — otherwise you'll burn hours troubleshooting something that has nothing to do with your configuration.
The Big Gotcha: SonarQube Server Version
Key point: sonarqube-cli (and the sonarqube-mcp-server behind it) does not support SonarQube Server 9.x. You must be running 10.x or later.
Our team had SonarQube 9.9 LTS deployed — a rock-solid long-term support release that plenty of organizations still run. We followed the official docs to the letter, set up sonarqube-cli, ran authentication, and kept getting connection errors with no useful message. Spent a good chunk of time ruling out network issues, token problems, and firewall rules.
The root cause turned out to be simple: sonarqube-mcp-server calls the next-generation SonarQube API (/api/v2/ prefix). Those endpoints were introduced in version 10.x. They simply do not exist on a 9.9 instance.
Fix: We spun up a fresh SonarQube Server 10.x instance, pointed the config at it, and everything worked immediately.
Check your version before anything else. Log into the SonarQube console and look in the bottom-right corner or under Administration > System. If you see a 9.x version number, you need to upgrade or deploy a separate 10.x instance before continuing with any of the steps below.
Version Compatibility at a Glance
| SonarQube Server Version | Works with sonarqube-cli / MCP? |
|---|---|
| 9.9 LTS and below | ❌ Not supported |
| 10.0 – 10.x | ✅ Supported |
| SonarQube Cloud | ✅ Supported |
Architecture Overview
Understanding the three-layer stack makes troubleshooting much easier.
Claude Code
│
├── sonarqube-agent-plugins ← Plugin layer: slash commands and Skills
│ └── /sonar-analyze, /sonar-integrate, etc.
│
├── sonarqube-cli (sonar) ← CLI layer: lightweight tool for auth and analysis
│ └── ~/.local/share/sonarqube-cli/bin/sonar
│
└── sonarqube-mcp-server ← MCP layer: containerized server for deep analysis
└── Runs via Docker/Podman, calls SonarQube Server API
Each layer has a distinct responsibility:
- sonarqube-agent-plugins: The official plugin bundle that injects Sonar slash commands and Skills into Claude Code
- sonarqube-cli: A lightweight CLI tool that handles authentication and basic analysis — no container required
- sonarqube-mcp-server: A Docker/Podman container that acts as the MCP server, powering advanced capabilities like coverage, quality gates, and duplication detection
Prerequisites
Make sure the following are in place before you start:
-
Node.js 18+: Required by the plugin's
SessionStarthook script (scripts/setup.js) -
Docker or Podman: The MCP Server runs as a container
- On macOS in corporate environments, Docker Desktop is often disallowed (licensing); use Podman instead (see the macOS section below)
- Linux and Windows can use Docker directly
- SonarQube Server 10.x (or SonarQube Cloud): Deployed and reachable over the network
- Browser logged into SonarQube: The OAuth authorization step requires a browser session
Installation
Step 1: Install the sonarqube-agent-plugins Plugin
Open Claude Code and run these two slash commands in order:
/plugin marketplace add SonarSource/sonarqube-agent-plugins
/plugin install sonarqube@sonar
Then reload the plugins (or start a fresh Claude Code session):
/reload-plugins
Verify: Type /sonar in Claude Code. If you see a list of Sonar commands, the plugin installed correctly.
Step 2: Run the Integration Wizard
In Claude Code, run:
/sonar-integrate
This launches an interactive wizard that walks you through: installing sonarqube-cli → connecting to SonarQube Server → completing OAuth authorization → registering the MCP Server.
2.1 Install sonarqube-cli
The wizard installs sonarqube-cli automatically in the first step. The CLI lands at:
~/.local/share/sonarqube-cli/bin/sonar
If you get a "command not found" error when running sonar later, add it to your PATH manually:
# Add to ~/.zshrc or ~/.bashrc
echo 'export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
2.2 Connect to SonarQube Server
The wizard prompts you to choose a connection method. Select option 4: "Type something" and enter your SonarQube Server URL directly:
http://your-sonarqube-server:9000/
Reminder: this URL must point to a SonarQube 10.x or later instance. Pointing at a 9.9 server here will cause auth and scan failures downstream.
2.3 Authenticate
Once the wizard recognizes the server address, it tells you the next step. Run the auth command in the Claude Code terminal or a separate terminal window:
sonar auth login -s http://your-sonarqube-server:9000/
This automatically opens a browser and navigates to the SonarQube authorization page. Click Allow connection to complete the flow.
Order matters: make sure your browser is already logged into SonarQube before running this command. If you're not logged in, the redirect will take you to the login screen first and the flow gets messier.
Once you've clicked Allow in the browser, return to Claude Code and tell it "Authorization complete." Claude Code will run a connection health check, and if everything passes, moves to the next step.
2.4 Choose Integration Scope
The wizard asks where to apply the SonarQube integration:
-
Current project: Takes effect only in the current working directory. Config is written to the project-level
.claude/directory. Recommended for shared codebases. -
Global: Applies to all projects. Config goes into
~/.claude/.
After you choose, Claude Code automatically registers the MCP Server in the appropriate config file.
Once this is done, exit Claude Code completely.
Corporate Network: Replacing the Docker Image Mirror
In corporate environments, Docker Hub (registry-1.docker.io) is often blocked. You'll need to point the sonarqube-mcp-server image at an internal mirror.
Edit the MCP Config
The MCP config lives in ~/.claude.json (global) or .claude/claude.json (project-level). Find the sonarqube entry under mcpServers and update the image reference.
Example (using a JFrog Artifactory proxy):
// Before
"image": "sonarsource/sonarqube-mcp-server:latest"
// After — internal mirror proxy
"image": "jfrog.yourcompany.com/external-docker-public-virtual/sonarsource/sonarqube-mcp-server:latest"
Mapping rule: prepend your internal registry host to the original image name: <registry>/<original-image>:<tag>. Check with your infrastructure team for the exact proxy URL and path prefix.
macOS: Using Podman Instead of Docker
Many corporate macOS environments prohibit Docker Desktop due to licensing requirements. Podman is a fully open-source, Docker-compatible alternative.
Install Podman
Download the macOS installer (.pkg) from podman.io and double-click to install.
Add Podman to your PATH:
echo 'export PATH="/opt/podman/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Verify:
which podman
# /opt/podman/bin/podman
podman --version
# podman version 5.x.x
Initialize the Podman Machine
On macOS, Podman needs a lightweight VM to run containers (similar to Docker Desktop's VM layer):
# First-time setup (downloads ~500 MB base image — takes a while)
podman machine init
# Start the VM
podman machine start
# Check status
podman machine list
# NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE
# podman-machine-default* applehv ... Currently running 5 2GiB 100GiB
After every Mac restart, Podman Machine does not start automatically. You need to run podman machine start manually, or configure a launchd service to start it on login.
Start Up and Verify
With all configuration done, quit Claude Code fully and relaunch it so the MCP config takes effect.
On the first launch, Claude Code will pull the sonarqube-mcp-server container image. This will be slow the first time — give it a minute or two. Then run:
/mcp
When sonarqube shows as connected, the integration is live.
Optional: sonar-project.properties
Create a sonar-project.properties file in your project root to pre-declare project metadata. This lets the analysis commands auto-detect the project without needing you to pass the project key manually each time:
sonar.projectKey=my-project
sonar.projectName=My Project
sonar.projectVersion=1.0
sonar.sources=src
sonar.sourceEncoding=UTF-8
Command Reference
CLI Commands (no MCP required)
| Command | Description |
|---|---|
/sonar-integrate |
Re-run setup: re-authenticate, re-register MCP, reinstall hooks |
/sonar-list-projects [keyword] |
List accessible SonarQube projects |
/sonar-list-issues [project] [--severity CRITICAL] |
Search and filter project issues |
/sonar-fix-issue <rule> <file>[:<line>] |
Fix a specific rule violation in a file |
MCP Commands (requires connected MCP Server)
| Command | Description |
|---|---|
/sonar-analyze [file path] |
Analyze a single file and display issues |
/sonar-quality-gate [project] [--branch] |
Check Quality Gate status |
/sonar-coverage [project] [--max N] [--file] |
View code coverage |
/sonar-duplication [project] [--pr N] [--file] |
View code duplication |
/sonar-dependency-risks [project] [--pr N] |
View dependency risks (requires Advanced Security) |
Example: Scan a Single File
/sonar-analyze ./src/main/java/com/example/UserService.java
Claude Code calls the MCP Server, runs the analysis, and returns a structured list of bugs, vulnerabilities, and code smells with fix suggestions. You can immediately ask Claude to act on the results:
Fix all CRITICAL issues found in the last scan
Troubleshooting
Authentication Fails
# Re-authenticate (overwrites the old token)
sonar auth login -s http://your-sonarqube-server:9000/
# Check auth status
sonar auth status
Run this any time you deploy a new SonarQube Server or switch instances.
sonar Command Not Found
echo 'export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
MCP Server Fails to Start
- Verify the container runtime is working:
docker infoorpodman info - Double-check the image path in
~/.claude.json(especially for corporate mirror setups) - On macOS, confirm Podman Machine is running:
podman machine start
404 / API Errors When Connecting to SonarQube (the most common failure)
If you see 404s or API errors during auth or scanning, the server version is almost certainly the culprit:
# Check the server version via API
curl http://your-sonarqube-server:9000/api/server/version
If the response is 9.9.x, you need to upgrade to 10.x. There is no workaround — the new API endpoints simply don't exist on 9.x.
Summary
Here's what we covered:
- Architecture: Three layers — agent-plugins, sonarqube-cli, and mcp-server — each with a distinct role
- The version trap: SonarQube Server must be 10.x or later; 9.9 LTS is not supported
- Full installation: Plugin marketplace → integration wizard → auth → MCP registration
- Corporate network setup: Internal mirror proxy for Docker images + Podman as a Docker Desktop replacement on macOS
- Daily workflow: File scanning, quality gates, coverage, and fix commands
With this setup in place, Claude Code isn't just helping you write code faster — it's also helping you write code that passes quality gates before it ever hits CI. That's what AI-assisted development should actually look like.
References
- SonarSource/sonarqube-agent-plugins — Official Claude Code plugin repository
- SonarQube MCP Server — MCP Server implementation
- Podman Installation Guide
Questions or issues? Drop a comment below.
Top comments (0)