# SonarQube MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives **Cursor AI** (and any MCP-compatible AI) live access to SonarQube — so you can ask questions like:

> *"What SonarQube issues are in this file?"*
> *"What does Sonar say about my PR?"*
> *"Fix all issues in config.ts for PR 257"*

…and Cursor fetches the data itself, no copy-pasting JSON.

---

## Tools exposed

| Tool | When AI uses it |
|---|---|
| `sonar_get_pr_metrics` | "What's my coverage?" / "Does Sonar pass?" / "What are the Sonar metrics on PR 257?" |
| `sonar_get_pr_issues` | "What issues are on my PR?" / "What does Sonar say?" |
| `sonar_get_file_issues` | "What issues are in this file?" / "Fix issues in config.ts" |
| `sonar_get_duplication_report` | "Which files have duplicated code?" / "What's the duplication?" |

---

## Architecture

```
Cursor AI
    │  (MCP protocol over stdio)
    ▼
SonarQube MCP Server (this repo)
    │  (HTTPS with Teleport client certificates)
    ▼
Teleport (company SSO gateway)
    │
    ▼
SonarQube API
```

> **Note:** SonarQube at OpenGov is behind [Teleport](https://goteleport.com/), a secure access gateway. The server uses Teleport client certificates generated by `tsh apps login`. If your SonarQube is directly accessible (no Teleport), the server works without `tsh`.

---

## Prerequisites

- **Node.js 18+** (Node 22 recommended)
- **`tsh` (Teleport CLI)** — only needed if SonarQube is behind Teleport
- **SonarQube user token** — generate at SonarQube → My Account → Security → Generate Token
- **Cursor** (or any MCP-compatible AI client)

---

## Installation

### Step 1 — Clone the repo

```bash
git clone https://github.com/rahulsingh-cloud/SonarQube-MCP-Server.git
cd SonarQube-MCP-Server
```

### Step 2 — Install dependencies

```bash
npm install
```

### Step 3 — Build

```bash
npm run build
```

This compiles `index.ts` → `dist/index.js`.

---

## Configuration

### Step 4 — Get your SonarQube token

1. Open SonarQube in your browser and log in
2. Go to **My Account → Security → Generate Token**
3. Name it `cursor-mcp`, click **Generate**, copy the token

### Step 5 — Register the MCP server with Cursor

Edit (or create) the Cursor MCP config file. The location depends on your OS:

| OS | Path |
|---|---|
| **Windows** | `C:\Users\<YourName>\.cursor\mcp.json` |
| **macOS** | `~/.cursor/mcp.json` |
| **Linux** | `~/.cursor/mcp.json` |

---

#### Windows

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\SonarQube-MCP-Server\\dist\\index.js"],
      "env": {
        "SONARQUBE_TOKEN": "squ_your_token_here",
        "SONARQUBE_URL": "https://your-sonarqube-host",
        "SONARQUBE_PROJECT": "your-project-key"
      }
    }
  }
}
```

> **Tip (Windows):** Use double backslashes `\\` in the path, or use forward slashes `/` — both work.

---

#### macOS / Linux

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "node",
      "args": ["/Users/yourname/SonarQube-MCP-Server/dist/index.js"],
      "env": {
        "SONARQUBE_TOKEN": "squ_your_token_here",
        "SONARQUBE_URL": "https://your-sonarqube-host",
        "SONARQUBE_PROJECT": "your-project-key"
      }
    }
  }
}
```

> **Tip (macOS):** Use `pwd` inside the cloned repo folder to get the full path.

---

**Replace in both:**
- `your-project-key` — found in SonarQube → Project → Project Information
- `squ_your_token_here` — your SonarQube token from Step 4
- `https://your-sonarqube-host` — your SonarQube base URL (e.g. `https://sonarqube.yourcompany.com`)

### Step 6 — Restart Cursor

Close Cursor completely (Quit, not just close the window) and reopen it.

- **Windows:** Right-click Cursor in the system tray → Quit
- **macOS:** `Cmd+Q` or Cursor menu → Quit Cursor

You'll see `sonarqube` listed with a green dot under **Cursor Settings → MCP**.

---

## If SonarQube is behind Teleport (OpenGov setup)

Teleport is a secure access gateway. The server automatically detects and uses Teleport client certificates if `tsh` is installed and logged in.

### Install `tsh` (Teleport CLI)

**Windows:**
1. Download from https://goteleport.com/download/ → Windows → `.exe` installer
2. Run the installer
3. Add the install folder to your `Path` environment variable (e.g. `C:\Program Files\Teleport Connect\Programs`)
4. Restart your terminal

```powershell
tsh version   # verify
```

**macOS (Homebrew):**
```bash
brew install teleport
tsh version   # verify
```

**macOS (manual):**
1. Download from https://goteleport.com/download/ → macOS → `.pkg` installer
2. Run the installer — `tsh` is added to `/usr/local/bin` automatically

```bash
tsh version   # verify
```

---

### Log in to Teleport

Works the same on Windows, macOS, and Linux:

```bash
# Step 1 — Log in via browser SSO (Okta)
tsh login --proxy=opengov.teleport.sh --skip-version-check

# Step 2 — Get access to SonarQube specifically
tsh apps login sonarqube-engops-production --skip-version-check

# Step 3 — Verify access
tsh apps ls --skip-version-check
```

After `tsh login`, your browser opens for Okta SSO. After authenticating, return to the terminal and run steps 2 and 3.

The server automatically finds the certificates at:

**macOS / Linux:**
```
~/.tsh/keys/opengov.teleport.sh/<username>-app/opengov.teleport.sh/sonarqube-engops-production.crt
~/.tsh/keys/opengov.teleport.sh/<username>-app/opengov.teleport.sh/sonarqube-engops-production.key
```

**Windows:**
```
C:\Users\<YourName>\.tsh\keys\opengov.teleport.sh\<username>-app\opengov.teleport.sh\sonarqube-engops-production.crt
C:\Users\<YourName>\.tsh\keys\opengov.teleport.sh\<username>-app\opengov.teleport.sh\sonarqube-engops-production.key
```

Supports both:
- **Teleport v18+** — `.crt` / `.key` files
- **Teleport v17 and older** — `-x509.pem` files

> **Cert expiry:** Teleport certificates expire (typically 12 hours). Run `tsh apps login sonarqube-engops-production --skip-version-check` again and restart Cursor when they expire.

---

## Usage

Once connected, just ask Cursor in plain English:

```
# Get PR metrics
"What does SonarQube say about PR 257?"
"Does my PR pass Sonar?"
"What's my coverage on PR 257?"

# Get file issues
"What SonarQube issues are in apps/web/src/og-assist/tools/config.ts?"
"Fix all issues in this file for PR 257"

# Get PR issues
"What issues were introduced in PR 257?"
"Show me all new code smells on my PR"

# Get duplication
"Which files have duplicated code in PR 257?"
"What's the duplication on my PR?"
```

Cursor selects the right tool automatically based on your question.

---

## Manual testing

You can test the server without Cursor by piping JSON-RPC directly.

**macOS / Linux:**
```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  SONARQUBE_TOKEN=your_token \
  SONARQUBE_URL=https://your-sonarqube \
  SONARQUBE_PROJECT=your-project \
  node dist/index.js

# Call a tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sonar_get_pr_metrics","arguments":{"pullRequest":"257"}}}' | \
  SONARQUBE_TOKEN=your_token \
  SONARQUBE_URL=https://your-sonarqube \
  SONARQUBE_PROJECT=your-project \
  node dist/index.js
```

**Windows (PowerShell):**
```powershell
$env:SONARQUBE_TOKEN = "your_token"
$env:SONARQUBE_URL = "https://your-sonarqube"
$env:SONARQUBE_PROJECT = "your-project"

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sonar_get_pr_metrics","arguments":{"pullRequest":"257"}}}' | node dist/index.js
```

---

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `SONARQUBE_TOKEN` | ✅ Yes | — | SonarQube user token (`squ_...`) |
| `SONARQUBE_URL` | No | `https://sonarqube-engops-production.opengov.teleport.sh` | SonarQube base URL |
| `SONARQUBE_PROJECT` | No | `payroll-app-web` | SonarQube project key |

---

## Project structure

```
SonarQube-MCP-Server/
  ├── index.ts          ← MCP server source (all logic)
  ├── dist/index.js     ← compiled output (run this)
  ├── package.json
  ├── tsconfig.json
  └── README.md
```

---

## How it works

1. Cursor reads `~/.cursor/mcp.json` at startup and launches the server as a background process
2. The server registers 4 tools with names and descriptions
3. When you ask a question, Cursor's AI reads the tool descriptions and decides which tool to call
4. The server makes an HTTPS request to SonarQube (with Teleport certs if applicable) and returns the data
5. Cursor uses the data to answer your question or take action

---

## Troubleshooting

| Problem | Fix |
|---|---|
| `sonarqube` not showing in Cursor MCP | Fully quit and reopen Cursor (`Cmd+Q` on Mac, tray → Quit on Windows) |
| `Teleport session required` error | Run `tsh apps login sonarqube-engops-production --skip-version-check` |
| `401 Unauthorized` | Token is wrong or expired — generate a new one from SonarQube → My Account → Security |
| `Cert/key not found` | Run `tsh apps login` first to generate the certificates |
| Certs expired | Run `tsh apps login sonarqube-engops-production --skip-version-check` and restart Cursor |
| `tsh: command not found` (Mac) | Run `brew install teleport` or add the install path to your `PATH` |
| `tsh: command not found` (Windows) | Add `C:\Program Files\Teleport Connect\Programs` to your `Path` environment variable |

---

## License

MIT