SonarQube MCP Server

SonarQube MCP 服务器

SonarQube MCP 服务器是一个模型上下文协议 (MCP) 服务器，能够无缝集成 SonarQube Server 或 Cloud，以保障代码质量和安全。 它还支持直接在代理上下文中分析代码片段。

快速设置

🚀 生成您的配置

最快的入门方式是使用 SonarQube MCP 服务器配置生成器 – 这是一个交互式工具，可为您偏好的 AI 代理客户端生成即用型配置。

手动设置

如果您希望自行配置，最简单的方法是使用我们在 sonarsource/sonarqube-mcp 上的容器镜像。使用 sonarsource/sonarqube-mcp 可获取自动更新（配合 --pull=always），或固定到某个版本标签（例如 sonarsource/sonarqube-mcp:1.19.0.2785）以实现可复现的部署。如果您想在本地构建，请阅读下文。

注意： 虽然以下示例使用 docker，但任何兼容 OCI 的容器运行时均可使用（例如 Podman、nerdctl）。只需将 docker 替换为您偏好的工具即可。

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "<YOUR_TOKEN>",
        "SONARQUBE_ORG": "<YOUR_ORG>"
      }
    }
  }
}

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
        "SONARQUBE_URL": "<YOUR_SERVER_URL>"
      }
    }
  }
}

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  --env SONARQUBE_ORG=$SONAR_ORG \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  --env SONARQUBE_URL=$SONAR_URL \
  -- docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_URL sonarsource/sonarqube-mcp

[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"]
env = { "SONARQUBE_TOKEN" = "<YOUR_USER_TOKEN>", "SONARQUBE_ORG" = "<YOUR_ORG>" }

[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"]
env = { "SONARQUBE_TOKEN" = "<YOUR_TOKEN>", "SONARQUBE_URL" = "<YOUR_SERVER_URL>" }

gemini extensions install https://github.com/SonarSource/sonarqube-agent-plugins

/mcp add

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_ORG, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=<YOUR_TOKEN>,SONARQUBE_ORG=<YOUR_ORG>
Tools: *

Server Name: sonarqube
Server Type: Local (Press 1)
Command: docker
Arguments: run, --init, --pull=always, --rm, -i, -e, SONARQUBE_TOKEN, -e, SONARQUBE_URL, sonarsource/sonarqube-mcp
Environment Variables: SONARQUBE_TOKEN=<YOUR_USER_TOKEN>,SONARQUBE_URL=<YOUR_SERVER_URL>
Tools: *

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_ORG",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_TOKEN",
        "SONARQUBE_ORG": "COPILOT_MCP_SONARQUBE_ORG"
      },
      "tools": ["*"]
    }
  }
}

{
  "mcpServers": {
    "sonarqube": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "--rm",
        "-i",
        "-e",
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_USER_TOKEN",
        "SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL"
      },
      "tools": ["*"]
    }
  }
}

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "-i",
        "--rm",
        "-e", 
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_ORG",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YOUR_TOKEN>",
        "SONARQUBE_ORG": "<YOUR_ORG>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "--pull=always",
        "-i",
        "--rm",
        "-e", 
        "SONARQUBE_TOKEN",
        "-e",
        "SONARQUBE_URL",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_TOKEN": "<YOUR_USER_TOKEN>",
        "SONARQUBE_URL": "<YOUR_SERVER_URL>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "sonarqube_token": "YOUR_SONARQUBE_TOKEN",
  "sonarqube_org": "SONARQUBE_ORGANIZATION_KEY",
  "docker_path": "DOCKER_PATH"
}

{
  "sonarqube_token": "YOUR_SONARQUBE_USER_TOKEN",
  "sonarqube_url": "YOUR_SONARQUBE_SERVER_URL",
  "docker_path": "DOCKER_PATH"
}

💡 提示： 我们建议定期拉取最新镜像，或在报告问题前拉取，以确保您拥有最新的功能和修复。

手动安装

您可以通过在 MCP 服务器配置文件中复制以下代码片段来手动安装 SonarQube MCP 服务器：

• 连接 SonarQube Cloud：

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_ORG",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_ORG": "<org>"
    }
  }
}

• 连接 SonarQube Server：

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

与 SonarQube for IDE 集成

SonarQube MCP 服务器可以与 SonarQube for IDE 集成，以进一步增强您的开发工作流程，直接在您的 IDE 中提供更好的代码分析和洞察。

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_ORG",
      "-e",
      "SONARQUBE_IDE_PORT",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_ORG": "<org>",
      "SONARQUBE_IDE_PORT": "<64120-64130>"
    }
  }
}

配置

根据您的环境，您应提供特定的环境变量。

基础

运行 MCP 服务器时，您应添加以下变量：

工作区挂载（减少上下文膨胀）

默认情况下，分析工具 analyze_code_snippet 要求代理将完整的文件内容作为 fileContent 参数传递。对于大文件或在会话中分析许多文件时，这会显著增加上下文窗口的使用量和成本。 解决方案： 将项目目录挂载到容器中的 /app/mcp-workspace。检测到此挂载后，服务器会使用项目相关的 filePath 参数直接从磁盘读取文件——文件内容不会经过代理上下文。

{
  "args": [
    "run", "-i", "--rm", "--init", "--pull=always",
    "-e", "SONARQUBE_TOKEN",
    "-e", "SONARQUBE_ORG",
    "-v", "/path/to/your/project:/app/mcp-workspace",
    "sonarsource/sonarqube-mcp"
  ]
}

挂载生效时：

• 如果您的组织有相应授权，run_advanced_code_analysis 将变为可用
• analyze_code_snippet：需要 filePath，且不使用 fileContent——服务器以相同方式解析文件

选择性工具集启用

默认情况下，仅启用重要的工具集以减少上下文开销。您可以根据需要启用其他工具集。

docker run --init --pull=always -i --rm \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_ORG="<org>" \
  -e SONARQUBE_TOOLSETS="analysis,issues,quality-gates" \
  sonarsource/sonarqube-mcp

docker run --init --pull=always -i --rm \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_ORG="<org>" \
  -e SONARQUBE_READ_ONLY="true" \
  sonarsource/sonarqube-mcp

SonarQube Cloud

要启用完整功能，必须在启动服务器前设置以下环境变量：

示例：

• SonarQube Cloud：仅需 SONARQUBE_TOKEN 和 SONARQUBE_ORG
• SonarQube Cloud US：设置 SONARQUBE_TOKEN、SONARQUBE_ORG 和 SONARQUBE_URL=https://sonarqube.us

SonarQube Server

⚠️ 连接到 SonarQube Server 需要 USER 类型的令牌，如果使用项目令牌或全局令牌将无法正常工作。

💡 配置提示（stdio 模式）：SONARQUBE_ORG 的存在与否决定了您是连接到 SonarQube Cloud 还是 Server。如果设置了 SONARQUBE_ORG，则使用 SonarQube Cloud；否则，使用 SonarQube Server。

传输模式

MCP 规范 定义了两种传输机制：Stdio 和 Streamable HTTP。SonarQube MCP Server 两者均支持：

注意： Streamable HTTP 是当前的 MCP 网络传输方式。早期 MCP 版本中旧的仅 SSE HTTP 传输已弃用，不受支持。

1. Stdio（默认 - 推荐用于本地开发）

推荐用于本地开发和单用户设置的模式，大多数 MCP 客户端都使用此模式。

示例 - Docker 配合 SonarQube Cloud：

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": ["run", "--init", "--pull=always", "-i", "--rm", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "<your-token>",
        "SONARQUBE_ORG": "<your-org>"
      }
    }
  }
}

2. HTTP（Streamable HTTP）

未加密的 Streamable HTTP 传输。对于多用户部署，请改用 HTTPS。

⚠️ 不推荐： 本地开发请使用 Stdio，多用户生产部署请使用 HTTPS（Streamable HTTP）。

• 如果在服务器启动时设置了 SONARQUBE_ORG，所有请求都将路由到该组织。客户端不得发送 SONARQUBE_ORG 头——否则会导致错误。
• 如果在服务器启动时未设置 SONARQUBE_ORG，每个客户端必须在每个请求中提供 SONARQUBE_ORG 头。 客户端还可以通过在每个请求中提供 SONARQUBE_TOOLSETS 和/或 SONARQUBE_READ_ONLY 头来缩小可见工具的范围；这些会在服务器级配置的基础上应用额外的过滤——它们只能缩小范围，绝不能扩大范围。 请求之间不维护会话状态。

已弃用： SONARQUBE_TOKEN 请求头仍被接受以保持向后兼容，但将在未来版本中移除。请迁移到 Authorization: Bearer <token>。

3. HTTPS（基于 TLS 的可流式 HTTP）（推荐用于多用户生产部署）

通过 TLS 加密的安全可流式 HTTP 传输。需要 SSL 证书。

✅ 生产环境推荐： 在通过可流式 HTTP 为多用户部署 MCP 服务器时使用 HTTPS。出于安全考虑，服务器默认绑定到 127.0.0.1（本地主机）。

SSL 证书配置（可选）：

示例 - 使用 SonarQube Cloud 的 Docker：

注意： 在容器中运行时，设置 SONARQUBE_HTTP_HOST=0.0.0.0 以便容器监听所有接口，并使运行时的端口映射正常工作，同时设置 SONARQUBE_MCP_IN_CONTAINER=true 以告知服务器它位于容器内部。官方 Docker 镜像会自动设置后者；使用其他 OCI 运行时（Podman、Kubernetes、Nomad 等）时，请自行设置。主机端的端口标志控制着谁可以从容器外部访问服务器。SONARQUBE_HTTP_HOST=0.0.0.0 仅控制服务器在容器内部的监听位置——浏览器 CORS 默认仍允许本地主机来源。

对于在本地机器上运行的服务器（仅可从本地主机访问）：

docker run --init --pull=always -p 127.0.0.1:8443:8443 \
  -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  -e SONARQUBE_TRANSPORT=https \
  -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  -e SONARQUBE_HTTP_PORT=8443 \
  -e SONARQUBE_TOKEN="<init-token>" \
  -e SONARQUBE_ORG="<your-org>" \
  sonarsource/sonarqube-mcp

对于可从网络访问的服务器（远程部署）：

docker run --init --pull=always -p 8443:8443 \
  -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \
  -e SONARQUBE_TRANSPORT=https \
  -e SONARQUBE_HTTP_HOST=0.0.0.0 \
  -e SONARQUBE_HTTP_PORT=8443 \
  -e SONARQUBE_TOKEN="<init-token>" \
  -e SONARQUBE_ORG="<your-org>" \
  sonarsource/sonarqube-mcp

客户端配置（SonarQube Cloud）：

{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "SONARQUBE_ORG": "<your-org>",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

客户端配置（SonarQube Server）：

{
  "mcpServers": {
    "sonarqube-https": {
      "url": "https://your-server:8443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "SONARQUBE_TOOLSETS": "issues,quality-gates",
        "SONARQUBE_READ_ONLY": "true"
      }
    }
  }
}

注意： SONARQUBE_TOOLSETS 和 SONARQUBE_READ_ONLY 是可选的按请求头，用于针对特定请求缩小服务器级工具集的范围。它们只能缩小范围——不能启用工具集或解除超出服务器启动时配置的限制。

注意： 对于本地开发，请改用标准输入输出传输（默认）。HTTPS 可流式 HTTP 适用于具有适当 SSL 证书的多用户生产部署。

服务端点

在可流式 HTTP 模式（http 或 https）下运行时，除了位于 /mcp 的 MCP 端点外，服务器还会公开一些无需身份验证的服务端点。这些端点用于服务间通信（监控、编排、客户端兼容性检查），不需要 Authorization 头。

这些端点在以标准输入输出传输方式运行时不可用。

自定义证书

如果您的 SonarQube Server 使用自签名证书或来自私有证书颁发机构（CA）的证书，您可以将自定义证书添加到容器中，它们会自动安装。

docker run --init --pull=always -i --rm \
  -v /path/to/your/certificates/:/usr/local/share/ca-certificates/:ro \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_URL="<url>" \
  sonarsource/sonarqube-mcp

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run",
      "--init",
      "--pull=always",
      "-i",
      "--rm",
      "-v",
      "/path/to/your/certificates/:/usr/local/share/ca-certificates/:ro",
      "-e",
      "SONARQUBE_TOKEN",
      "-e",
      "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

代理

SonarQube MCP Server 通过标准 Java 代理系统属性支持 HTTP 和 SOCKS5 代理。

工具

分析

• analyze_code_snippet - 使用 SonarQube 分析器分析文件内容，以识别代码质量和安全问题。始终分析完整的文件内容以确保准确性。可选择将结果过滤到特定的代码片段。

  用法：

  • 挂载工作区时（推荐）：传递 filePath（项目相对路径）——服务器直接读取文件，避免文件内容进入代理上下文窗口
  • 未挂载工作区时：传递完整的 fileContent 以进行完整文件分析（报告所有问题）
  • 添加可选的 codeSnippet 以过滤结果——仅报告片段内的问题（片段位置自动检测）

  参数：

  • projectKey - SonarQube 项目密钥 - 必需字符串 （定义 SONARQUBE_PROJECT_KEY 时忽略）
  • filePath - 要分析的文件的相对项目路径（例如 src/main/java/MyClass.java）。当工作区挂载在 /app/mcp-workspace 时使用 - 字符串
  • fileContent - 作为字符串的完整文件内容。未挂载工作区时必需 - 字符串
  • codeSnippet - 用于过滤问题的代码片段（必须与 fileContent 中的内容匹配） - 字符串
  • language - 代码语言（例如 'java'、'python'、'js'、'ts'、'tsx'、'jsx'） - 字符串
  • scope - 文件范围：MAIN 或 TEST（默认：MAIN） - 字符串

  支持的语言： Java、Kotlin、Python、Ruby、Go、JavaScript（js、jsx）、TypeScript（ts、tsx）、JSP、PHP、XML、HTML、CSS、CloudFormation、Kubernetes、Terraform、Azure Resource Manager、Ansible、Docker、密钥检测

启用与 SonarQube for IDE 的集成时：

• analyze_file_list - 使用 SonarQube for IDE 分析当前工作目录中的文件。此工具连接到正在运行的 SonarQube for IDE 实例，对文件列表执行代码质量分析。

  • file_absolute_paths - 要分析的绝对文件路径列表 - 必需字符串数组

• toggle_automatic_analysis - 启用或禁用 SonarQube for IDE 自动分析。启用后，SonarQube for IDE 将在工作目录中的文件被修改时自动分析它们。禁用后，自动分析将关闭。

  • enabled - 启用或禁用自动分析 - 必需布尔值

为您的 SonarQube Cloud 组织启用高级分析时：

需要将工作区挂载在 /app/mcp-workspace

• run_advanced_code_analysis - 在 SonarQube Cloud 上对单个文件运行高级代码分析。组织从 MCP 配置中推断。
  • projectKey - 项目密钥 - 必需字符串 （定义 SONARQUBE_PROJECT_KEY 时忽略）
  • branchName - 用于检索最新分析上下文的分支名称 - 必需字符串
  • filePath - 要分析的文件的相对项目路径（例如 src/main/java/MyClass.java）。 - 必需字符串
  • fileScope - 定义文件来源范围：'MAIN' 或 'TEST'（默认：MAIN） - 字符串

覆盖率

• search_files_by_coverage - 按覆盖率（升序——覆盖率最低的优先）搜索项目中的文件。此工具可帮助识别需要改进测试覆盖率的文件。

  • projectKey - 要搜索的项目键 - 必填字符串 （当 SONARQUBE_PROJECT_KEY 已定义时忽略）
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • maxCoverage - 最大覆盖率阈值（0-100）。仅返回覆盖率 <= 此值的文件 - 数字
  • pageIndex - 页码索引（从 1 开始，默认：1） - 数字
  • pageSize - 每页大小（默认：100，最大：500） - 数字

• get_file_coverage_details - 获取特定文件的逐行覆盖率信息，包括哪些确切行未被覆盖以及哪些行具有部分覆盖的分支。此工具可帮助精确定位需要添加测试覆盖的位置。在通过 search_files_by_coverage 识别出覆盖率较低的文件后使用。

  • key - 文件键（例如 my_project:src/foo/Bar.java） - 必填字符串
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • from - 要分析的第一行（从 1 开始，默认：1） - 数字
  • to - 要分析的最后一行（含）。如果未指定，则返回所有行 - 数字

依赖项风险

注意：依赖项风险仅在连接到 SonarQube Server 2025.4 Enterprise 或更高版本并启用 SonarQube Advanced Security 时可用。

• search_dependency_risks - 搜索 SonarQube 项目的软件组成分析问题（依赖项风险），并与分析的项目、应用程序或组合中出现的版本配对。
  • projectKey - 项目键 - 必填字符串 （当 SONARQUBE_PROJECT_KEY 已定义时忽略）
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • pageIndex - 可选的页码索引（从 1 开始，默认：1） - 整数
  • pageSize - 可选的每页大小。必须大于 0 且小于或等于 500（默认：100） - 整数

企业

注意：企业仅在连接到 SonarQube Cloud 时可用。

• list_enterprises - 列出您在 SonarQube Cloud 中有权访问的企业。使用此工具查找可与其他工具一起使用的企业 ID。
  • enterpriseKey - 可选的企业键，用于筛选结果 - 字符串

问题

• change_sonar_issue_status - 将 SonarQube 问题的状态更改为“接受”、“误报”或“重新打开”一个问题。

  • key - 问题键 - 必填字符串
  • status - 问题的新状态 - 必填枚举 {"accept", "falsepositive", "reopen"}

• search_sonar_issues_in_projects - 在我组织的项目中搜索 SonarQube 问题。

  • projects - 可选的 Sonar 项目列表 - 字符串数组
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • severities - 可选的严重程度列表，用于筛选。可能的值：INFO、LOW、MEDIUM、HIGH、BLOCKER - 字符串数组
  • impactSoftwareQualities - 可选的软件质量列表，用于筛选。可能的值：MAINTAINABILITY、RELIABILITY、SECURITY - 字符串数组
  • issueStatuses - 可选的问题状态列表，用于筛选。可能的值：OPEN、CONFIRMED、FALSE_POSITIVE、ACCEPTED、FIXED、IN_SANDBOX - 字符串数组
  • issueKey - 可选的问题键，用于获取特定问题 - 字符串
  • p - 可选的页码（默认：1） - 整数
  • ps - 可选的每页大小。必须大于 0 且小于或等于 500（默认：100） - 整数

安全热点

• search_security_hotspots - 在 SonarQube 项目中搜索安全热点。

  • projectKey - 项目或应用程序键 - 必填字符串 （当 SONARQUBE_PROJECT_KEY 已定义时忽略）
  • hotspotKeys - 要检索的特定安全热点键的逗号分隔列表 - 字符串数组
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • files - 可选的文件路径列表，用于筛选 - 字符串数组
  • status - 可选的状态筛选器：TO_REVIEW、REVIEWED - 字符串
  • resolution - 可选的解决方式筛选器：FIXED、SAFE、ACKNOWLEDGED - 字符串
  • sinceLeakPeriod - 筛选自泄漏期（新代码）以来创建的热点 - 布尔值
  • onlyMine - 仅显示分配给我的热点 - 布尔值
  • p - 可选的页码（默认：1） - 整数
  • ps - 可选的每页大小。必须大于 0 且小于或等于 500（默认：100） - 整数

• show_security_hotspot - 获取特定安全热点的详细信息，包括规则详情、代码上下文、数据流和评论。

  • hotspotKey - 安全热点键 - 必填字符串

• change_security_hotspot_status - 通过更改状态来审查安全热点。当标记为 REVIEWED 时，必须指定解决方式（FIXED、SAFE 或 ACKNOWLEDGED）。

  • hotspotKey - 安全热点键 - 必填字符串
  • status - 新状态 - 必填枚举 {"TO_REVIEW", "REVIEWED"}
  • resolution - 当状态为 REVIEWED 时的解决方式 - 枚举 {"FIXED", "SAFE", "ACKNOWLEDGED"}
  • comment - 可选的审查评论 - 字符串

语言

• list_languages - 列出此 SonarQube 实例支持的所有编程语言。
  • q - 可选的模式，用于匹配语言键/名称 - 字符串

度量

• get_component_measures - 获取组件（项目、目录、文件）的 SonarQube 度量。
  • projectKey - 项目键 - 当 SONARQUBE_PROJECT_KEY 未配置时为必填字符串
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • metricKeys - 可选的度量键列表，用于检索（例如 ncloc、complexity、violations、coverage） - 字符串数组
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串

指标

• search_metrics - 搜索 SonarQube 指标。
  • p - 可选的页码（默认：1） - 整数
  • ps - 可选的每页大小。必须大于 0 且小于或等于 500（默认：100） - 整数

组合

• list_portfolios - 列出 SonarQube 中可用的企业组合，支持筛选和分页选项。

  对于 SonarQube Server：

  • q - 可选的搜索查询，用于按名称或键筛选组合 - 字符串
  • favorite - 如果为 true，则仅返回收藏的组合 - 布尔值
  • pageIndex - 可选的从 1 开始的页码（默认：1） - 整数
  • pageSize - 可选的每页大小，最大 500（默认：100） - 整数

  对于 SonarQube Cloud：

  • enterpriseId - 企业 uuid。仅当提供 'favorite' 参数且值为 true 时可以省略 - 字符串
  • q - 可选的搜索查询，用于按名称筛选组合 - 字符串
  • favorite - 如果省略 'enterpriseId' 参数，则必须为 true。如果为 true，则仅返回登录用户收藏的组合。当 'draft' 为 true 时不能为 true - 布尔值
  • draft - 如果为 true，则仅返回登录用户创建的草稿。当 'favorite' 为 true 时不能为 true - 布尔值
  • pageIndex - 可选的要获取的页面索引（默认：1） - 整数
  • pageSize - 可选的要获取的页面大小（默认：50） - 整数

项目

• search_my_sonarqube_projects - 查找 SonarQube 项目。响应是分页的。

  • page - 可选的页码 - 字符串

• list_branches - 列出项目的长生命周期分支（例如 main、develop、master）。在 SonarQube Cloud 上仅返回 LONG 个分支，在 SonarQube Server 上返回 BRANCH 个条目——名称可安全用于其他工具的 branch 参数。对于拉取请求，请改用 list_pull_requests。

  • projectKey - 项目键（例如 my_project） - 必填字符串 （当 SONARQUBE_PROJECT_KEY 已定义时忽略）

• list_pull_requests - 列出项目的所有拉取请求。在分析其覆盖率、问题或质量之前，使用此工具查找可用的拉取请求。返回拉取请求键/ID，可与其他工具（例如 search_files_by_coverage、get_file_coverage_details）一起使用。对于长生命周期分支，请改用 list_branches。

  • projectKey - 项目键（例如 my_project） - 必填字符串 （当 SONARQUBE_PROJECT_KEY 已定义时忽略）

质量门

• get_project_quality_gate_status - 获取 SonarQube 项目的质量门状态。

  • analysisId - 可选的分析 ID - 字符串
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • projectId - 可选的项目 ID - 字符串
  • projectKey - 可选的项目键 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串

• list_quality_gates - 列出我的 SonarQube 中的所有质量门。

规则

• show_rule - 显示有关 SonarQube 规则的详细信息。
  • key - 规则键 - 必填字符串

重复

• search_duplicated_files - 在 SonarQube 项目中搜索存在代码重复的文件。默认情况下，自动获取所有页面中的所有重复文件（最多 10,000 个文件）。仅返回存在重复的文件。

  • projectKey - 项目键 - 必填字符串 （当 SONARQUBE_PROJECT_KEY 已定义时忽略）
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串
  • pageSize - 可选的每页结果数，用于手动分页（最大：500）。如果未指定，则自动获取所有重复文件 - 整数
  • pageIndex - 可选的页码，用于手动分页（从 1 开始）。如果未指定，则自动获取所有重复文件 - 整数

• get_duplications - 获取文件的重复情况。需要对文件所在项目具有浏览权限。

  • key - 文件键 - 必填字符串
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串

源代码

• get_raw_source - 从 SonarQube 获取源代码原始文本。需要对文件拥有“查看源代码”权限。

  • key - 文件键 - 必填字符串
  • branch - 可选的长生命周期分支名称（例如 main、develop）。使用 list_branches 查找有效名称 - 字符串
  • pullRequest - 可选的拉取请求键/ID。使用 list_pull_requests 查找有效键 - 字符串

• get_scm_info - 获取 SonarQube 源文件的 SCM 信息。需要对文件所属项目拥有“查看源代码”权限。

  • key - 文件键 - 必填字符串
  • commits_by_line - 如果值为 false，则按 SCM 提交对行进行分组，否则显示每行的提交信息 - 字符串
  • from - 要返回的第一行。从 1 开始 - 数字
  • to - 要返回的最后一行（含） - 数字

系统

注意：系统工具仅在连接到 SonarQube Server 时可用。

• get_system_health - 获取 SonarQube Server 实例的健康状态。返回 GREEN（完全正常运行）、YELLOW（可用但需关注）或 RED（不可用）。

• get_system_info - 获取有关 SonarQube Server 系统配置的详细信息，包括 JVM 状态、数据库、搜索索引和设置。需要“管理”权限。

• get_system_logs - 以纯文本格式获取 SonarQube Server 系统日志。需要系统管理权限。

  • name - 可选的要获取的日志名称。可选值：access、app、ce、deprecation、es、web。默认值：app - 字符串

• ping_system - Ping SonarQube Server 系统以检查其是否存活。以纯文本形式返回“pong”。

• get_system_status - 获取有关 SonarQube Server 的状态信息。返回状态（STARTING、UP、DOWN、RESTARTING、DB_MIGRATION_NEEDED、DB_MIGRATION_RUNNING）、版本和 ID。

Webhooks

• create_webhook - 为 SonarQube 组织或项目创建新的 webhook。需要对指定项目拥有“管理”权限，或拥有全局“管理”权限。

  • name - Webhook 名称 - 必填字符串
  • url - Webhook URL - 必填字符串
  • projectKey - 可选的项目键，用于项目特定的 webhook - 字符串
  • secret - 可选的 webhook 密钥，用于保护 webhook 负载 - 字符串

• list_webhooks - 列出 SonarQube 组织或项目的所有 webhook。需要对指定项目拥有“管理”权限，或拥有全局“管理”权限。

  • projectKey - 可选的项目键，用于列出项目特定的 webhook - 字符串

上下文增强

# macOS/Linux (Bash/Zsh)
export SONARQUBE_TOKEN="{<YourUserToken>}"

{
  "mcpServers": {
    "sonarqube-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-e", "SONARQUBE_TOOLSETS",
        "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_ORG": "<YourOrganizationKey>",
        "SONARQUBE_PROJECT_KEY": "<YourProjectKey>",
        "SONARQUBE_TOOLSETS": "cag"
      }
    }
  }
}

智能体就绪度

注意：智能体就绪度工具仅在 SonarQube Cloud 上可用，并且需要为您的组织启用该功能。

• start_agentic_readiness_assessment - 启动项目的智能体就绪度评估。立即返回状态 PENDING 和一个 assessmentId。使用 get_agentic_readiness_assessment 轮询结果。

  • projectKey - 项目键 - 必填字符串 （定义 SONARQUBE_PROJECT_KEY 时忽略）
  • branch - 要评估的分支。省略则使用项目的默认分支 - 字符串

• get_agentic_readiness_assessment - 检索评估结果。使用相同的 assessmentId 重新调用，直到状态为 COMPLETED、FAILED 或 INTERRUPTED。完成后，返回总体级别以及每个支柱的细分，包含建议的操作和证据。

  • assessmentId - start_agentic_readiness_assessment 返回的评估 ID - 必填字符串

• list_agentic_readiness_assessments - 列出项目的所有评估，最新的在前。使用 get_agentic_readiness_assessment 获取完整的支柱级别结果。

  • projectKey - 要列出评估的项目键 - 必填字符串 （定义 SONARQUBE_PROJECT_KEY 时忽略）
  • branch - 按分支名称过滤评估。省略则列出所有分支的评估 - 字符串
  • pageIndex - 基于 1 的页面索引（默认值：1） - 数字
  • pageSize - 每页项目数，最大 100（默认值：50） - 数字

示例提示

设置好 SonarQube MCP 服务器后，以下是一些常见实际场景的示例提示：

My quality gate is failing for my project. Can you help me understand why and fix the most critical issues?

The quality gate on my feature branch is red. What do I need to fix to get it passing before I can merge to main?

I'm about to merge my pull request <#247> for the <web-app> project. Can you check if there are any quality issues I should address first?

We're deploying to production tomorrow. Can you check the quality gate status and alert me to any critical issues in this branch?

I want to reduce technical debt in my project. What are the top issues I should prioritize?

Our code coverage dropped below 70%. Can you identify which files have the lowest coverage and help me improve it?

I have 15 new code smells in my latest commit. Can you explain what they are and help me fix them?

SonarQube flagged a critical security vulnerability in <AuthController.java>. What's the issue and how do I fix it?

We need to pass a security audit. Can you check all our projects for security vulnerabilities and create a prioritized list of what needs to be fixed?

Are there any known vulnerabilities in our dependencies? Check this project for dependency risks.

I just wrote this authentication function. Can you analyze it for security issues and code quality problems before I commit?

Review the changes in <src/database/migrations> for any potential bugs or security issues.

Give me a health report for my project: quality gate status, number of bugs, Security Hotspots, and code coverage.

Compare code quality between our main branch and the develop branch. Are we introducing new issues?

What are the most common rule violations across all our projects? We might need to update our coding standards.

Show me all the issues that were marked as false positives in the last month. Are we seeing patterns that suggest our rules need adjustment?

构建

推荐使用 sonarsource/sonarqube-mcp 容器镜像。

若要在不使用 Docker 的情况下以独立 JAR 运行服务器，请从 SonarSource 二进制文件仓库 下载预构建的发行版。每个已发布的版本都会以 sonarqube-mcp-server-<version>.jar 的形式发布在那里（例如，sonarqube-mcp-server-1.19.0.2785.jar）。

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-jar",
      "<path_to_sonarqube_mcp_server_jar>"
    ],
    "env": {
      "STORAGE_PATH": "<path_to_your_mcp_storage>",
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_ORG": "<org>"
    }
  }
}

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-jar",
      "<path_to_sonarqube_mcp_server_jar>"
    ],
    "env": {
      "STORAGE_PATH": "<path_to_your_mcp_storage>",
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

./gradlew clean build -x test

./gradlew :dependencies --write-locks
./gradlew :its:dependencies --write-locks

故障排除

默认情况下，应用程序日志会写入 STORAGE_PATH/logs/mcp.log 文件。要完全禁用文件日志记录，请设置 SONARQUBE_LOG_TO_FILE_DISABLED=true。

常见问题

“功能无法使用”或“缺少工具/功能”

你可能正在运行过时的 Docker 镜像。Docker 会在本地缓存镜像，因此你不会自动收到更新。

解决方案： 更新到最新版本：

docker pull sonarsource/sonarqube-mcp

拉取最新镜像后，重启你的 MCP 客户端以使用更新后的版本。

或者，在你的 docker run 命令中添加 --pull=always 标志，以便始终检查并拉取最新版本：

docker run --init --pull=always -i --rm -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

“我想固定到特定版本”

浏览 sonarsource/sonarqube-mcp 上的可用标签，并引用你想要的版本：

docker pull sonarsource/sonarqube-mcp:1.19.0.2785

docker run --init -i --rm \
  -e SONARQUBE_TOKEN -e SONARQUBE_ORG \
  sonarsource/sonarqube-mcp:1.19.0.2785

在你的 MCP 客户端配置中，使用 sonarsource/sonarqube-mcp:<version> 代替 sonarsource/sonarqube-mcp，并移除 --pull=always，这样 Docker 就不会静默升级镜像。

数据与遥测

此服务器会收集匿名使用数据并将其发送给 SonarSource，以帮助改进产品。不会收集任何源代码或 IP 地址，且 SonarSource 不会与任何其他人共享这些数据。可以通过以下系统属性或环境变量禁用遥测收集：TELEMETRY_DISABLED=true。点击此处查看所收集数据的样本。

许可证

版权所有 2025 SonarSource。

根据 SONAR Source-Available License v1.0 许可。在遵守本文档的前提下使用 SonarQube MCP Server 属于非竞争性目的，因此 SSAL 允许此类使用。

你通过 MCP 使用 SonarQube 的行为受 SonarQube Cloud 服务条款 或 SonarQube Server 条款和条件 的约束，包括仅将结果数据用于你的内部软件开发目的。