SonarQube

SonarQube MCP Server

SonarQube MCP Server là một máy chủ Model Context Protocol (MCP), cho phép tích hợp liền mạch với SonarQube Server hoặc Cloud để đảm bảo chất lượng và bảo mật mã. Máy chủ này cũng hỗ trợ phân tích đoạn mã trực tiếp trong ngữ cảnh của tác tử.

Bắt đầu với thiết lập nhanh, hoặc tìm hiểu thêm về hệ sinh thái sản phẩm SonarQube.

Thiết lập nhanh

🚀 Tạo cấu hình

Cách nhanh nhất để bắt đầu là sử dụng Trình tạo cấu hình SonarQube MCP Server – một công cụ tương tác tạo cấu hình sẵn sàng sử dụng cho ứng dụng khách AI mà bạn chọn.

Thiết lập thủ công

Nếu muốn tự cấu hình, cách đơn giản nhất là sử dụng ảnh container của chúng tôi tại sonarsource/sonarqube-mcp. Sử dụng sonarsource/sonarqube-mcp để tự động cập nhật (với --pull=always), hoặc ghim vào thẻ phiên bản (ví dụ: sonarsource/sonarqube-mcp:1.19.0.2785) để triển khai có thể tái lập. Một số bản phát hành cũng được gắn thẻ theo phiên bản SonarQube Server tương ứng, theo định dạng <SQS major>.<SQS minor>.<patch> (ví dụ: sonarsource/sonarqube-mcp:2026.5.0), trong đó số bản vá tăng lên theo mỗi bản phát hành MCP nhắm đến phiên bản SonarQube Server đó. Đọc phần bên dưới nếu bạn muốn tự xây dựng cục bộ.

Lưu ý: Mặc dù các ví dụ bên dưới sử dụng docker, mọi môi trường chạy container tương thích OCI đều hoạt động (ví dụ: Podman, nerdctl). Chỉ cần thay docker bằng công cụ bạn muốn dùng.

{
  "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"
}

💡 Mẹo: Chúng tôi khuyên bạn nên thường xuyên tải ảnh mới nhất hoặc tải trước khi báo cáo sự cố để đảm bảo bạn có các tính năng và bản sửa lỗi mới nhất.

Cài đặt thủ công

Bạn có thể cài đặt thủ công máy chủ SonarQube MCP bằng cách sao chép đoạn mã sau vào tệp cấu hình máy chủ MCP:

• Để kết nối với 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>"
    }
  }
}

• Để kết nối với 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>"
    }
  }
}

Tích hợp với SonarQube for IDE

SonarQube MCP Server có thể tích hợp với SonarQube for IDE để cải thiện hơn nữa quy trình phát triển, cung cấp khả năng phân tích mã và thông tin chuyên sâu tốt hơn ngay trong IDE của bạn.

{
  "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>"
    }
  }
}

Cấu hình

Tùy thuộc vào môi trường, bạn cần cung cấp các biến môi trường cụ thể.

Cơ bản

Bạn nên thêm biến sau khi chạy MCP Server:

Gắn kết không gian làm việc (Giảm phình to ngữ cảnh)

Theo mặc định, công cụ phân tích analyze_code_snippet yêu cầu tác tử truyền toàn bộ nội dung tệp dưới dạng đối số fileContent. Với các tệp lớn hoặc khi phân tích nhiều tệp trong một phiên, điều này làm tăng đáng kể mức sử dụng cửa sổ ngữ cảnh và chi phí.

Giải pháp: gắn kết thư mục dự án của bạn vào container tại /app/mcp-workspace. Khi phát hiện thấy điểm gắn kết này, máy chủ sẽ đọc tệp trực tiếp từ đĩa bằng đối số filePath tương đối với dự án — nội dung tệp không bao giờ đi qua ngữ cảnh của tác tử.

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

Khi có điểm gắn kết, các công cụ phân tích đọc tệp trực tiếp bằng filePath; không cần fileContent.

Qua stdio, phương thức phân tích được chọn khi khởi động (tùy thuộc vào các bộ công cụ được bật):

• SonarQube Cloud: Phân tích Vortex (run_advanced_code_analysis) khi có điểm gắn kết không gian làm việc và ít nhất một tổ chức đủ điều kiện; nếu không thì dùng phân tích cục bộ. Phân tích Vortex chỉ chấp nhận các tổ chức đủ điều kiện.
• SonarQube Server: Phân tích Vortex cho các phiên bản đủ điều kiện (yêu cầu điểm gắn kết không gian làm việc); phân tích cục bộ cho các phiên bản không có Vortex.

Phân tích cục bộ sử dụng SonarQube for IDE nếu được kết nối, hoặc analyze_code_snippet. Nếu không có điểm gắn kết, phân tích đoạn mã yêu cầu fileContent.

Trên Cloud stdio, SONARQUBE_ORG giới hạn việc kiểm tra quyền sử dụng ở tổ chức đó. Để sử dụng đoạn mã cho tất cả tổ chức, hãy đặt SONARQUBE_FORCE_LOCAL_ANALYSIS=true, bật bộ công cụ analysis và khởi động lại. Cài đặt này chỉ ảnh hưởng đến Cloud stdio.

Qua HTTP/HTTPS, Cloud và Server hỗ trợ analyze_code_snippet khi máy chủ MCP có SONARQUBE_TOKEN lúc khởi động và bộ công cụ analysis được bật. Token khởi động là bắt buộc để khởi tạo trình phân tích (các plugin Cloud được tải xuống ẩn danh); các lệnh gọi sử dụng token của người gọi và, trên Cloud, tổ chức được chọn cho yêu cầu để truy xuất hồ sơ chất lượng và quy tắc đang hoạt động. Nếu không có token khởi động, tính năng phân tích đoạn mã và tải xuống trình phân tích sẽ bị tắt, ngay cả khi có SONARQUBE_FORCE_LOCAL_ANALYSIS=true. Không yêu cầu quyền sử dụng Vortex.

Bật công cụ có chọn lọc

Các ứng dụng MCP tải mọi công cụ được bật — tên, mô tả và lược đồ đầu vào — vào ngữ cảnh của tác tử trong mỗi cuộc hội thoại. Giới hạn danh sách đó bằng SONARQUBE_TOOLSETS giúp giảm mức sử dụng ngữ cảnh và chi phí token của mỗi phiên.

Theo mặc định, chỉ các bộ công cụ quan trọng được bật. Chỉ bật thêm bộ công cụ khi bạn cần.

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

Với stdio, hãy cấu hình các biến môi trường sau:

Ví dụ:

• SonarQube Cloud: Chỉ cần SONARQUBE_TOKEN. SONARQUBE_ORG cố định tổ chức khi được thiết lập.
• SonarQube Cloud US: Thiết lập SONARQUBE_TOKEN và SONARQUBE_URL=https://sonarqube.us; SONARQUBE_ORG là tùy chọn.

SonarQube Server

Yêu cầu phiên bản: Cần SonarQube Server 2025.1 (SQS) hoặc 25.1 (SonarQube Community Build) trở lên. Khi khởi động, máy chủ MCP đọc phiên bản của phiên bản SonarQube được kết nối và thoát kèm lỗi nếu phiên bản quá cũ (ví dụ: các bản phát hành Server 9.x/10.x cũ và Community Build 24.x không được hỗ trợ). SonarQube Cloud không chịu kiểm tra này.

⚠️ Kết nối với SonarQube Server yêu cầu token loại USER và sẽ không hoạt động đúng nếu dùng token dự án hoặc token toàn cục.

💡 Mẹo cấu hình (chế độ stdio): Nếu không có URL, token sẽ mặc định dùng SonarQube Cloud. Thiết lập SONARQUBE_URL cho SonarQube Server hoặc một khu vực Cloud khác. SONARQUBE_ORG cố định tổ chức Cloud khi được thiết lập.

Trong stdio, thiết lập SONARQUBE_ORG sẽ cố định tổ chức Cloud. Các đối số của công cụ organization bị lược khỏi lược đồ và bị từ chối, tương tự như projectKey khi SONARQUBE_PROJECT_KEY được thiết lập.

Khi không thiết lập SONARQUBE_ORG, tác tử có thể gọi list_organizations để tìm các khóa, tên, ID và UUID của tổ chức mà tài khoản người dùng của bạn có thể truy cập, sau đó truyền khóa làm đối số organization tùy chọn cho các công cụ nhận biết tổ chức. Stdio giữ tổ chức được phát hiện duy nhất làm mặc định; nếu không có hoặc có nhiều tổ chức thì tổ chức mặc định chưa được xác định. Đối số của công cụ chỉ áp dụng cho lần gọi đó và không bao giờ thay đổi tổ chức mặc định đã phát hiện. Việc tra cứu hồ sơ đoạn mã và quy tắc sử dụng tổ chức được chọn cho lần gọi đó.

Đối với yêu cầu token qua HTTP/HTTPS, SONARQUBE_ORG cấp máy chủ vẫn được hỗ trợ để tương thích nhưng không còn được khuyến nghị và sẽ ghi cảnh báo khi khởi động. Biến này cố định tổ chức cho mọi yêu cầu và từ chối tiêu đề tổ chức của máy khách cũng như các đối số organization của công cụ. Khi không cấu hình tổ chức cấp máy chủ, tiêu đề SONARQUBE_ORG tùy chọn của máy khách sẽ cố định tổ chức cho yêu cầu đó và không cho phép các đối số organization của công cụ. Nếu không có tiêu đề, hãy dùng đối số của công cụ. Các công cụ cần tổ chức sẽ hướng dẫn cách tìm tổ chức khi thiếu tất cả các giá trị này. Việc tìm tổ chức và các công cụ có API chỉ sử dụng mã định danh tài nguyên không cần đối số tổ chức. Tìm kiếm vấn đề nhận biết tổ chức và kiểm tra quyền sử dụng rủi ro phụ thuộc sẽ dùng tổ chức đã chọn. Khi cấu hình OAuth, SONARQUBE_ORG cấp máy chủ sẽ bị từ chối. Các yêu cầu OAuth cũng từ chối tiêu đề tổ chức; hãy chọn tổ chức thông qua đối số của công cụ.

Các công cụ ngữ cảnh Vortex sử dụng tổ chức đã cấu hình hoặc tổ chức duy nhất được phát hiện khi khởi động. Đối số tổ chức trong thời gian chạy không cấu hình lại công cụ ngữ cảnh được ủy quyền; nếu tổ chức khi khởi động chưa được xác định thì sẽ bỏ qua proxy đó. Công cụ tích hợp sẵn run_advanced_code_analysis kiểm tra quyền sử dụng Vortex kết hợp cho tổ chức được chọn trong mỗi lần gọi.

Chế độ truyền tải

Đặc tả MCP định nghĩa hai cơ chế truyền tải: Stdio và Streamable HTTP. SonarQube MCP Server hỗ trợ cả hai:

Lưu ý: Streamable HTTP là phương thức truyền tải mạng MCP hiện tại. Phương thức truyền tải HTTP chỉ dùng SSE cũ hơn từ các phiên bản MCP trước đã không còn được khuyến nghị và không được hỗ trợ.

1. Stdio (Mặc định - Được khuyến nghị cho phát triển cục bộ)

Chế độ được khuyến nghị cho phát triển cục bộ và thiết lập một người dùng, được hầu hết máy khách MCP sử dụng.

Ví dụ - Docker với 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)

Phương thức truyền tải Streamable HTTP không mã hóa. Thay vào đó, hãy dùng HTTPS cho triển khai nhiều người dùng.

⚠️ Không được khuyến nghị: Dùng Stdio cho phát triển cục bộ hoặc HTTPS (Streamable HTTP) cho triển khai sản xuất nhiều người dùng.

• SONARQUBE_ORG là tiêu đề yêu cầu tùy chọn dùng để cố định tổ chức cho yêu cầu đó. Cấu hình cấp máy chủ đã lỗi thời sẽ cố định tổ chức cho mọi yêu cầu và từ chối tiêu đề tổ chức cũng như đối số tổ chức của công cụ từ máy khách.
• Các công cụ nhận biết tổ chức chấp nhận đối số organization tùy chọn khi cả cấu hình máy chủ lẫn tiêu đề yêu cầu đều không cố định tổ chức. Nếu tổ chức đã được cố định, việc cung cấp đối số này sẽ bị từ chối.
• Khi không có giá trị mặc định, tác tử có thể gọi list_organizations chỉ bằng token của mình, sau đó truyền khóa đã chọn cho các công cụ tiếp theo.

Máy khách cũng có thể thu hẹp các công cụ hiển thị theo từng yêu cầu bằng cách cung cấp tiêu đề SONARQUBE_TOOLSETS và/hoặc SONARQUBE_READ_ONLY; các tiêu đề này áp dụng bộ lọc bổ sung bên cạnh cấu hình cấp máy chủ — chúng chỉ có thể thu hẹp phạm vi, không bao giờ mở rộng phạm vi. Không duy trì trạng thái phiên giữa các yêu cầu.

Đã lỗi thời: Đối với token SonarQube, tiêu đề yêu cầu SONARQUBE_TOKEN vẫn được chấp nhận để tương thích ngược nhưng sẽ bị loại bỏ trong phiên bản tương lai. Hãy chuyển sang Authorization: Bearer <token>.

3. HTTPS (HTTP dạng luồng qua TLS) (Được khuyến nghị cho triển khai sản xuất nhiều người dùng)

Truyền tải HTTP dạng luồng an toàn với mã hóa TLS. Yêu cầu chứng chỉ SSL.

✅ Được khuyến nghị cho môi trường sản xuất: Sử dụng HTTPS khi triển khai máy chủ MCP cho nhiều người dùng qua HTTP dạng luồng. Theo mặc định, máy chủ liên kết với 127.0.0.1 (localhost) để bảo mật.

Cấu hình chứng chỉ SSL (Tùy chọn):

Ví dụ - Docker với SonarQube Cloud:

Lưu ý: Khi chạy trong vùng chứa, hãy đặt SONARQUBE_HTTP_HOST=0.0.0.0 để vùng chứa lắng nghe trên tất cả giao diện và ánh xạ cổng của runtime hoạt động, đồng thời đặt SONARQUBE_MCP_IN_CONTAINER=true để thông báo cho máy chủ rằng nó đang ở bên trong vùng chứa. Docker image chính thức tự động đặt giá trị sau; hãy tự đặt khi dùng các OCI runtime khác (Podman, Kubernetes, Nomad, v.v.). Cờ cổng phía máy chủ kiểm soát ai có thể truy cập máy chủ từ bên ngoài vùng chứa. SONARQUBE_HTTP_HOST=0.0.0.0 chỉ kiểm soát nơi máy chủ lắng nghe bên trong vùng chứa — CORS của trình duyệt vẫn cho phép các nguồn gốc localhost theo mặc định.

Đối với máy chủ chạy cục bộ trên máy của bạn (chỉ có thể truy cập từ localhost):

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 \
  sonarsource/sonarqube-mcp

Đối với máy chủ có thể truy cập qua mạng (triển khai từ xa):

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 \
  sonarsource/sonarqube-mcp

Cấu hình máy khách (SonarQube Cloud):

Đối với các yêu cầu token SonarQube, hãy đặt tùy chọn SONARQUBE_ORG trong tiêu đề máy khách để cố định tổ chức của yêu cầu, hoặc bỏ qua để chọn tổ chức thông qua đối số công cụ.

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

Cấu hình máy khách (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"
      }
    }
  }
}

Lưu ý: SONARQUBE_TOOLSETS và SONARQUBE_READ_ONLY là các tiêu đề yêu cầu tùy chọn giúp thu hẹp bộ công cụ cấp máy chủ cho riêng yêu cầu đó. Chúng chỉ có thể thu hẹp phạm vi — không thể bật bộ công cụ hoặc gỡ bỏ các hạn chế vượt quá cấu hình khi khởi chạy máy chủ.

Lưu ý: Để phát triển cục bộ, hãy dùng truyền tải Stdio (mặc định). HTTP dạng luồng qua HTTPS dành cho triển khai sản xuất nhiều người dùng có chứng chỉ SSL phù hợp.

OAuth cho SonarQube Cloud được lưu trữ

Hỗ trợ OAuth dành cho dịch vụ MCP SonarQube Cloud được lưu trữ của Sonar. Hãy dùng máy khách MCP hỗ trợ OAuth và đăng nhập khi được nhắc; không cần thiết lập máy chủ OAuth trong cấu hình máy khách. Các máy khách hiện có dùng token SonarQube vẫn được hỗ trợ.

Các phạm vi mcp:tools:read và mcp:tools:write kiểm soát độc lập quyền truy cập vào các công cụ đọc và ghi, tùy theo quyền Cloud của bạn. Dùng list_organizations và đối số công cụ organization để chọn tổ chức.

Các triển khai tự lưu trữ tiếp tục dùng token SonarQube; OAuth cho SonarQube Server hiện chưa được hỗ trợ.

Điểm cuối dịch vụ

Khi chạy ở chế độ HTTP dạng luồng (http hoặc https), máy chủ cung cấp một số điểm cuối dịch vụ không cần xác thực bên cạnh điểm cuối MCP tại /mcp. Các điểm cuối này dành cho giao tiếp giữa các dịch vụ (giám sát, điều phối, kiểm tra khả năng tương thích của máy khách) và không yêu cầu tiêu đề Authorization.

Các điểm cuối này không khả dụng khi chạy với truyền tải Stdio.

Chứng chỉ tùy chỉnh

Nếu SonarQube Server của bạn dùng chứng chỉ tự ký hoặc chứng chỉ từ Tổ chức phát hành chứng chỉ (CA) riêng, bạn có thể thêm chứng chỉ tùy chỉnh vào vùng chứa để chúng được tự động cài đặt.

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>"
    }
  }
}

Proxy

SonarQube MCP Server hỗ trợ proxy HTTP và SOCKS5 thông qua các thuộc tính hệ thống proxy tiêu chuẩn của Java.

Chứng chỉ máy khách (TLS hai chiều)

Nếu SonarQube Server yêu cầu máy khách cung cấp chứng chỉ trong quá trình bắt tay TLS (TLS hai chiều), bạn có thể cung cấp keystore PKCS12 bằng cách gắn kết keystore vào vùng chứa và truyền vị trí của keystore qua JAVA_OPTS.

docker run --init --pull=always -i --rm \
  -v /path/to/client.p12:/etc/ssl/mcp/client.p12:ro \
  -e JAVA_OPTS="-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=<passphrase>" \
  -e SONARQUBE_TOKEN="<token>" \
  -e SONARQUBE_URL="<url>" \
  sonarsource/sonarqube-mcp

{
  "sonarqube": {
    "command": "docker",
    "args": [
      "run", "--init", "--pull=always", "-i", "--rm",
      "-v", "/path/to/client.p12:/etc/ssl/mcp/client.p12:ro",
      "-e", "JAVA_OPTS",
      "-e", "SONARQUBE_TOKEN",
      "-e", "SONARQUBE_URL",
      "sonarsource/sonarqube-mcp"
    ],
    "env": {
      "JAVA_OPTS": "-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=<passphrase>",
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

java \
  -Djavax.net.ssl.keyStore=/path/to/client.p12 \
  -Djavax.net.ssl.keyStoreType=PKCS12 \
  -Djavax.net.ssl.keyStorePassword=<passphrase> \
  -jar <path_to_sonarqube_mcp_server_jar>

{
  "sonarqube": {
    "command": "java",
    "args": [
      "-Djavax.net.ssl.keyStore=/path/to/client.p12",
      "-Djavax.net.ssl.keyStoreType=PKCS12",
      "-Djavax.net.ssl.keyStorePassword=<passphrase>",
      "-jar",
      "<path_to_sonarqube_mcp_server_jar>"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<token>",
      "SONARQUBE_URL": "<url>"
    }
  }
}

Công cụ

Phân tích

• analyze_code_snippet - Phân tích nội dung tệp bằng các bộ phân tích SonarQube để xác định vấn đề về chất lượng mã và bảo mật. Luôn phân tích toàn bộ nội dung tệp để đảm bảo độ chính xác. Có thể lọc kết quả theo một đoạn mã cụ thể.

  Không còn được khuyến nghị: analyze_code_snippet sẽ bị xóa trong một bản phát hành trong tương lai. Kết nối SonarQube for IDE để sử dụng analyze_file_list, hoặc bật tính năng phân tích Vortex cho tổ chức của bạn để sử dụng run_advanced_code_analysis (xem bên dưới).

  Cách sử dụng:

  • Khi đã gắn workspace (khuyến nghị): truyền filePath (đường dẫn tương đối với dự án) — máy chủ đọc trực tiếp tệp, giữ nội dung tệp bên ngoài cửa sổ ngữ cảnh của tác nhân
  • Khi chưa gắn workspace: truyền đầy đủ fileContent để phân tích toàn bộ tệp (báo cáo tất cả vấn đề)
  • Thêm codeSnippet tùy chọn để lọc kết quả — chỉ báo cáo các vấn đề nằm trong đoạn mã (tự động phát hiện vị trí đoạn mã)

  Tham số:

  • organization - Khóa tổ chức SonarQube Cloud - Chuỗi tùy chọn, chỉ dành cho Cloud
  • projectKey - Khóa dự án SonarQube - Chuỗi bắt buộc (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • filePath - Đường dẫn tương đối với dự án của tệp cần phân tích (ví dụ: src/main/java/MyClass.java). Được sử dụng khi workspace được gắn tại /app/mcp-workspace - Chuỗi
  • fileContent - Toàn bộ nội dung tệp dưới dạng chuỗi. Bắt buộc khi workspace chưa được gắn - Chuỗi
  • codeSnippet - Đoạn mã dùng để lọc vấn đề (phải khớp với nội dung trong fileContent) - Chuỗi
  • language - Ngôn ngữ của mã (ví dụ: 'java', 'python', 'js', 'ts', 'tsx', 'jsx') - Chuỗi
  • scope - Phạm vi của tệp: MAIN hoặc TEST (mặc định: MAIN) - Chuỗi

  Ngôn ngữ được hỗ trợ: Java, Kotlin, Python, Ruby, Go, JavaScript (js, jsx), TypeScript (ts, tsx), JSP, PHP, XML, HTML, CSS, CloudFormation, Kubernetes, Terraform, Azure Resource Manager, Ansible, Docker, phát hiện bí mật

Khi bật tích hợp với SonarQube for IDE: (hai công cụ này được gắn thẻ trong cả hai bộ công cụ analysis và ide)

• analyze_file_list - Phân tích các tệp trong thư mục làm việc hiện tại bằng SonarQube for IDE. Công cụ này kết nối với một phiên bản SonarQube for IDE đang chạy để phân tích chất lượng mã trên danh sách tệp.

  • file_absolute_paths - Danh sách đường dẫn tuyệt đối của các tệp cần phân tích - Chuỗi[] bắt buộc

• toggle_automatic_analysis - Bật hoặc tắt tính năng phân tích tự động của SonarQube for IDE. Khi được bật, SonarQube for IDE sẽ tự động phân tích các tệp khi chúng được sửa đổi trong thư mục làm việc. Khi bị tắt, tính năng phân tích tự động sẽ ngừng hoạt động.

  • enabled - Bật hoặc tắt tính năng phân tích tự động - Boolean bắt buộc

Trên SonarQube Server, stdio liệt kê các công cụ ngữ cảnh Vortex và run_advanced_code_analysis khi cả hai hub CAG và A3S đều được cấp quyền sử dụng.

Khi có thể sử dụng tính năng phân tích Vortex:

Yêu cầu workspace được gắn tại /app/mcp-workspace

• run_advanced_code_analysis - Chạy phân tích Vortex trên một tệp. SonarQube Server sử dụng phần giữ chỗ UUID nil.
  • organization - Khóa tổ chức SonarQube Cloud - Chuỗi tùy chọn, chỉ dành cho Cloud
  • projectKey - Khóa dự án - Chuỗi bắt buộc (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • branch - Tên nhánh dùng để truy xuất ngữ cảnh phân tích mới nhất - Chuỗi bắt buộc
  • filePath - Đường dẫn tương đối với dự án của tệp cần phân tích (ví dụ: src/main/java/MyClass.java). - Chuỗi bắt buộc
  • fileScope - Xác định phạm vi của tệp: 'MAIN' hoặc 'TEST' (mặc định: MAIN) - Chuỗi

Độ bao phủ

• search_files_by_coverage - Tìm kiếm các tệp trong dự án, sắp xếp theo độ bao phủ (tăng dần — tệp có độ bao phủ thấp nhất trước). Công cụ này giúp xác định các tệp cần cải thiện độ bao phủ kiểm thử.

  • projectKey - Khóa dự án cần tìm kiếm - Chuỗi bắt buộc (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • branch - Tên nhánh tùy chọn để phân tích theo nhánh. Dùng list_branches để tìm các tên hợp lệ - Chuỗi
  • pullRequest - Khóa/ID yêu cầu kéo tùy chọn. Dùng list_pull_requests để tìm các khóa hợp lệ - Chuỗi
  • maxCoverage - Ngưỡng độ bao phủ tối đa (0-100). Chỉ trả về các tệp có độ bao phủ <= giá trị này - Số
  • pageIndex - Chỉ mục trang (bắt đầu từ 1, mặc định: 1) - Số
  • pageSize - Kích thước trang (mặc định: 100, tối đa: 500) - Số

• get_file_coverage_details - Lấy thông tin độ bao phủ theo từng dòng cho một tệp cụ thể, bao gồm chính xác những dòng nào chưa được bao phủ và những dòng nào có nhánh được bao phủ một phần. Công cụ này giúp xác định chính xác vị trí cần bổ sung độ bao phủ kiểm thử. Sử dụng sau khi xác định các tệp có độ bao phủ thấp bằng search_files_by_coverage.

  • key - Khóa tệp (ví dụ: my_project:src/foo/Bar.java) - Chuỗi bắt buộc
  • branch - Tên nhánh tùy chọn để phân tích theo nhánh. Dùng list_branches để tìm các tên hợp lệ - Chuỗi
  • pullRequest - Khóa/ID yêu cầu kéo tùy chọn. Dùng list_pull_requests để tìm các khóa hợp lệ - Chuỗi
  • from - Dòng đầu tiên cần phân tích (bắt đầu từ 1, mặc định: 1) - Số
  • to - Dòng cuối cùng cần phân tích (bao gồm dòng này). Nếu không chỉ định, trả về tất cả các dòng - Số

Rủi ro phụ thuộc

Lưu ý: Rủi ro phụ thuộc yêu cầu SonarQube Advanced Security. Trên SonarQube Server, cần có phiên bản Enterprise 2025.4 trở lên.

• search_dependency_risks - Tìm kiếm các vấn đề phân tích thành phần phần mềm (rủi ro phụ thuộc) của một dự án SonarQube, cùng với các bản phát hành xuất hiện trong dự án, ứng dụng hoặc danh mục đầu tư được phân tích.
  • organization - Khóa tổ chức SonarQube Cloud - Chuỗi tùy chọn, chỉ dành cho Cloud
  • projectKey - Khóa dự án - Chuỗi bắt buộc (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • branch - Tên nhánh tùy chọn để phân tích theo nhánh. Dùng list_branches để tìm các tên hợp lệ - Chuỗi
  • pullRequest - Khóa/ID yêu cầu kéo tùy chọn. Dùng list_pull_requests để tìm các khóa hợp lệ - Chuỗi
  • pageIndex - Chỉ mục trang tùy chọn (bắt đầu từ 1, mặc định: 1) - Số nguyên
  • pageSize - Kích thước trang tùy chọn. Phải lớn hơn 0 và nhỏ hơn hoặc bằng 500 (mặc định: 100) - Số nguyên

Doanh nghiệp

Lưu ý: Chỉ có thể sử dụng doanh nghiệp khi kết nối với SonarQube Cloud.

• list_enterprises - Liệt kê các doanh nghiệp có trong SonarQube Cloud mà bạn có quyền truy cập. Dùng công cụ này để tìm ID doanh nghiệp có thể sử dụng với các công cụ khác.
  • enterpriseKey - Khóa doanh nghiệp tùy chọn để lọc kết quả - Chuỗi

Vấn đề

• change_sonar_issue_status - Thay đổi trạng thái của một vấn đề SonarQube thành "accept", "falsepositive" hoặc "reopen".

  • key - Khóa vấn đề - Chuỗi bắt buộc
  • status - Trạng thái mới của vấn đề - Enum bắt buộc {"accept", "falsepositive", "reopen"}
  • comment - Bình luận tùy chọn giải thích việc thay đổi trạng thái - Chuỗi

• search_sonar_issues_in_projects - Tìm kiếm các vấn đề SonarQube trong các dự án thuộc tổ chức của tôi.

  • organization - Khóa tổ chức SonarQube Cloud - Chuỗi tùy chọn, chỉ dành cho Cloud
  • projectKeys - Danh sách khóa dự án SonarQube tùy chọn - Chuỗi[]
  • branch - Tên nhánh tùy chọn để phân tích theo nhánh. Dùng list_branches để tìm các tên hợp lệ - Chuỗi
  • pullRequest - Khóa/ID yêu cầu kéo tùy chọn. Dùng list_pull_requests để tìm các khóa hợp lệ - Chuỗi
  • severities - Danh sách mức độ nghiêm trọng tùy chọn để lọc. Các giá trị có thể có: INFO, LOW, MEDIUM, HIGH, BLOCKER - Chuỗi[]
  • impactSoftwareQualities - Danh sách chất lượng phần mềm tùy chọn để lọc. Các giá trị có thể có: MAINTAINABILITY, RELIABILITY, SECURITY - Chuỗi[]
  • issueStatuses - Danh sách trạng thái vấn đề tùy chọn để lọc. Các giá trị có thể có: OPEN, CONFIRMED, FALSE_POSITIVE, ACCEPTED, FIXED, IN_SANDBOX - Chuỗi[]
  • tags - Danh sách thẻ vấn đề tùy chọn để lọc. Thẻ viết bằng chữ thường - Chuỗi[]
  • inNewCodePeriod - Chỉ trả về các vấn đề trong giai đoạn mã mới. Yêu cầu có chính xác một mục trong projectKeys và files - Boolean
  • issueKey - Khóa vấn đề tùy chọn để lấy một vấn đề cụ thể - Chuỗi
  • pageIndex - Chỉ mục trang tùy chọn, bắt đầu từ 1 (mặc định: 1) - Số nguyên
  • pageSize - Kích thước trang tùy chọn. Phải lớn hơn 0 và nhỏ hơn hoặc bằng 500 (mặc định: 100) - Số nguyên

Điểm nóng bảo mật

• search_security_hotspots - Tìm kiếm các điểm nóng bảo mật trong một dự án SonarQube.

  • projectKey - Khóa dự án hoặc ứng dụng - Chuỗi bắt buộc (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • hotspotKeys - Danh sách phân tách bằng dấu phẩy gồm các khóa điểm nóng bảo mật cụ thể cần truy xuất - Chuỗi[]
  • branch - Tên nhánh tùy chọn để phân tích theo nhánh. Dùng list_branches để tìm các tên hợp lệ - Chuỗi
  • pullRequest - Khóa/ID yêu cầu kéo tùy chọn. Dùng list_pull_requests để tìm các khóa hợp lệ - Chuỗi
  • files - Danh sách đường dẫn tệp tùy chọn để lọc - Chuỗi[]
  • status - Bộ lọc trạng thái tùy chọn: TO_REVIEW, REVIEWED - Chuỗi
  • resolution - Bộ lọc kết quả xử lý tùy chọn: FIXED, SAFE, ACKNOWLEDGED - Chuỗi
  • sinceLeakPeriod - Lọc các điểm nóng được tạo kể từ giai đoạn rò rỉ (mã mới) - Boolean
  • onlyMine - Chỉ hiển thị các điểm nóng được giao cho tôi - Boolean
  • pageIndex - Chỉ mục trang tùy chọn, bắt đầu từ 1 (mặc định: 1) - Số nguyên
  • pageSize - Kích thước trang tùy chọn. Phải lớn hơn 0 và nhỏ hơn hoặc bằng 500 (mặc định: 100) - Số nguyên

• show_security_hotspot - Lấy thông tin chi tiết về một điểm nóng bảo mật cụ thể, bao gồm thông tin quy tắc, ngữ cảnh mã, luồng và bình luận.

  • hotspotKey - Khóa điểm nóng bảo mật - Chuỗi bắt buộc

• change_security_hotspot_status - Đánh giá một điểm nóng bảo mật bằng cách thay đổi trạng thái. Khi đánh dấu là REVIEWED, bạn phải chỉ định kết quả xử lý (FIXED, SAFE hoặc ACKNOWLEDGED).

  • hotspotKey - Khóa điểm nóng bảo mật - Chuỗi bắt buộc
  • status - Trạng thái mới - Enum bắt buộc {"TO_REVIEW", "REVIEWED"}
  • resolution - Kết quả xử lý khi trạng thái là REVIEWED - Enum {"FIXED", "SAFE", "ACKNOWLEDGED"}
  • comment - Bình luận đánh giá tùy chọn - Chuỗi

Ngôn ngữ

• list_languages - Liệt kê tất cả ngôn ngữ lập trình được hỗ trợ trong phiên bản SonarQube này.
  • q - Mẫu tùy chọn để đối chiếu với khóa/tên ngôn ngữ - Chuỗi

Số liệu

• get_component_measures - Lấy số liệu SonarQube cho một thành phần (dự án, thư mục, tệp).
  • projectKey - Khóa dự án - Chuỗi bắt buộc khi SONARQUBE_PROJECT_KEY chưa được cấu hình
  • branch - Tên nhánh tùy chọn để phân tích theo nhánh. Dùng list_branches để tìm các tên hợp lệ - Chuỗi
  • metricKeys - Các khóa chỉ số tùy chọn cần truy xuất (ví dụ: ncloc, complexity, violations, coverage) - Chuỗi[]
  • pullRequest - Khóa/ID yêu cầu kéo tùy chọn. Dùng list_pull_requests để tìm các khóa hợp lệ - Chuỗi

Chỉ số

• search_metrics - Tìm kiếm các chỉ số SonarQube.
  • pageIndex - Chỉ mục trang tùy chọn, bắt đầu từ 1 (mặc định: 1) - Số nguyên
  • pageSize - Kích thước trang tùy chọn. Phải lớn hơn 0 và nhỏ hơn hoặc bằng 500 (mặc định: 100) - Số nguyên

Danh mục đầu tư

• list_portfolios - Liệt kê các danh mục đầu tư doanh nghiệp có trong SonarQube, với các tùy chọn lọc và phân trang.

  Đối với SonarQube Server:

  • q - Truy vấn tìm kiếm tùy chọn để lọc danh mục đầu tư theo tên hoặc khóa - Chuỗi
  • favorite - Nếu là true, chỉ trả về các danh mục đầu tư yêu thích - Boolean
  • pageIndex - Số trang tùy chọn, bắt đầu từ 1 (mặc định: 1) - Số nguyên
  • pageSize - Kích thước trang tùy chọn, tối đa 500 (mặc định: 100) - Số nguyên

  Dành cho SonarQube Cloud:

  • enterpriseId - UUID của Enterprise. Chỉ có thể bỏ qua nếu tham số 'favorite' được cung cấp với giá trị true - String
  • q - Truy vấn tìm kiếm tùy chọn để lọc danh mục đầu tư theo tên - String
  • favorite - Bắt buộc phải là true nếu bỏ qua tham số 'enterpriseId'. Nếu là true, chỉ trả về các danh mục đầu tư được người dùng đã đăng nhập yêu thích. Không thể là true khi 'draft' là true - Boolean
  • draft - Nếu là true, chỉ trả về các bản nháp do người dùng đã đăng nhập tạo. Không thể là true khi 'favorite' là true - Boolean
  • pageIndex - Chỉ mục trang tùy chọn cần lấy (mặc định: 1) - Integer
  • pageSize - Kích thước trang tùy chọn cần lấy (mặc định: 50) - Integer

Dự án

• list_organizations - Liệt kê các tổ chức SonarQube Cloud mà người dùng là thành viên, bao gồm khóa, tên, ID và UUID. Sử dụng khóa được trả về làm organization trong các công cụ tiếp theo.

• search_my_sonarqube_projects - Tìm dự án SonarQube. Phản hồi được phân trang.

  • organization - Khóa tổ chức SonarQube Cloud - Optional String, Cloud only
  • pageIndex - Chỉ mục trang tùy chọn, bắt đầu từ 1 (mặc định: 1) - Integer
  • pageSize - Kích thước trang tùy chọn. Phải lớn hơn 0 và nhỏ hơn hoặc bằng 500 (mặc định: 500) - Integer
  • q - Truy vấn tìm kiếm tùy chọn để lọc dự án theo tên (khớp một phần) hoặc khóa (khớp chính xác) - String

• list_branches - Liệt kê các nhánh đã được phân tích của một dự án.

  • SonarQube Cloud: trả về các nhánh tồn tại lâu dài (LONG) và ngắn hạn (SHORT) cùng các trường type và mergeBranch. Bộ lọc branchTypes là tùy chọn: ALL (mặc định), LONG hoặc SHORT.
  • SonarQube Server: trả về tất cả các nhánh đã được phân tích (tên, quality gate, ngày phân tích). Không có bộ lọc type, mergeBranch hoặc branchTypes.
  • Sử dụng tên nhánh được trả về làm tham số branch trong các công cụ khác. Đối với phân tích pull request, hãy sử dụng list_pull_requests.
  • projectKey - Khóa dự án (ví dụ: my_project) - Required String (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • branchTypes - (Chỉ dành cho SonarQube Cloud) Bộ lọc tùy chọn: ALL (mặc định), LONG hoặc SHORT - Enum {"ALL", "LONG", "SHORT"}

• list_pull_requests - Liệt kê tất cả pull request của một dự án. Sử dụng công cụ này để tìm pull request cho phân tích có trang trí PR (độ bao phủ, vấn đề, quality gate). Trả về khóa/ID pull request có thể dùng với các công cụ khác. Đối với phân tích dựa trên nhánh không có pull request, hãy sử dụng list_branches.

  • projectKey - Khóa dự án (ví dụ: my_project) - Required String (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)

Quality Gate

• get_project_quality_gate_status - Lấy trạng thái Quality Gate của dự án SonarQube.

  • analysisId - ID phân tích tùy chọn - String
  • branch - Tên nhánh tùy chọn cho phân tích dựa trên nhánh. Sử dụng list_branches để tìm các tên hợp lệ - String
  • projectId - ID dự án tùy chọn - String
  • projectKey - Khóa dự án tùy chọn - String
  • pullRequest - Khóa/ID pull request tùy chọn. Sử dụng list_pull_requests để tìm các khóa hợp lệ - String

• list_quality_gates - Liệt kê tất cả quality gate trong SonarQube của tôi.

  • organization - Khóa tổ chức SonarQube Cloud - Optional String, Cloud only

Quy tắc

• show_rule - Hiển thị thông tin chi tiết về một quy tắc SonarQube.
  • organization - Khóa tổ chức SonarQube Cloud - Optional String, Cloud only
  • key - Khóa quy tắc - Required String

Mã trùng lặp

• search_duplicated_files - Tìm kiếm các tệp có mã trùng lặp trong một dự án SonarQube. Theo mặc định, tự động lấy tất cả tệp trùng lặp trên mọi trang (tối đa 10.000 tệp). Chỉ trả về các tệp có mã trùng lặp.

  • projectKey - Khóa dự án - Required String (Bị bỏ qua khi SONARQUBE_PROJECT_KEY được xác định)
  • branch - Tên nhánh tùy chọn cho phân tích dựa trên nhánh. Sử dụng list_branches để tìm các tên hợp lệ - String
  • pullRequest - Khóa/ID pull request tùy chọn. Sử dụng list_pull_requests để tìm các khóa hợp lệ - String
  • pageSize - Số kết quả tùy chọn trên mỗi trang khi phân trang thủ công (tối đa: 500). Nếu không chỉ định, tự động lấy tất cả tệp trùng lặp - Integer
  • pageIndex - Số trang tùy chọn khi phân trang thủ công (bắt đầu từ 1). Nếu không chỉ định, tự động lấy tất cả tệp trùng lặp - Integer

• get_duplications - Lấy thông tin mã trùng lặp của một tệp. Yêu cầu quyền Browse đối với dự án chứa tệp.

  • key - Khóa tệp - Required String
  • branch - Tên nhánh tùy chọn cho phân tích dựa trên nhánh. Sử dụng list_branches để tìm các tên hợp lệ - String
  • pullRequest - Khóa/ID pull request tùy chọn. Sử dụng list_pull_requests để tìm các khóa hợp lệ - String

Mã nguồn

• get_raw_source - Lấy mã nguồn dưới dạng văn bản thuần từ SonarQube. Yêu cầu quyền 'See Source Code' đối với tệp.

  • key - Khóa tệp - Required String
  • branch - Tên nhánh tùy chọn cho phân tích dựa trên nhánh. Sử dụng list_branches để tìm các tên hợp lệ - String
  • pullRequest - Khóa/ID pull request tùy chọn. Sử dụng list_pull_requests để tìm các khóa hợp lệ - String

• get_scm_info - Lấy thông tin SCM của các tệp mã nguồn SonarQube. Yêu cầu quyền See Source Code đối với dự án chứa tệp.

  • key - Khóa tệp - Required String
  • commits_by_line - Nhóm các dòng theo commit SCM nếu giá trị là false; nếu không, hiển thị commit cho từng dòng - String
  • from - Dòng đầu tiên cần trả về. Bắt đầu từ 1 - Number
  • to - Dòng cuối cùng cần trả về (bao gồm) - Number

Hệ thống

Lưu ý: Các công cụ hệ thống chỉ khả dụng khi kết nối với SonarQube Server.

• get_system_health - Lấy trạng thái tình trạng của phiên bản SonarQube Server. Trả về GREEN (hoạt động đầy đủ), YELLOW (có thể sử dụng nhưng cần chú ý) hoặc RED (không hoạt động).

• get_system_info - Lấy thông tin chi tiết về cấu hình hệ thống SonarQube Server, bao gồm trạng thái JVM, cơ sở dữ liệu, chỉ mục tìm kiếm và cài đặt. Yêu cầu quyền 'Administer'.

• get_system_logs - Lấy nhật ký hệ thống SonarQube Server ở định dạng văn bản thuần. Yêu cầu quyền quản trị hệ thống.

  • name - Tên nhật ký tùy chọn cần lấy. Các giá trị có thể có: access, app, ce, deprecation, es, web. Mặc định: app - String

• ping_system - Ping hệ thống SonarQube Server để kiểm tra xem hệ thống có hoạt động hay không. Trả về 'pong' dưới dạng văn bản thuần.

• get_system_status - Lấy thông tin trạng thái của SonarQube Server. Trả về trạng thái (STARTING, UP, DOWN, RESTARTING, DB_MIGRATION_NEEDED, DB_MIGRATION_RUNNING), phiên bản và ID.

Webhook

• create_webhook - Tạo webhook mới cho tổ chức hoặc dự án SonarQube. Yêu cầu quyền 'Administer' đối với dự án được chỉ định hoặc quyền 'Administer' toàn cục.

  • organization - Khóa tổ chức SonarQube Cloud - Optional String, Cloud only
  • name - Tên webhook - Required String
  • url - URL webhook - Required String
  • projectKey - Khóa dự án tùy chọn cho webhook dành riêng cho dự án - String
  • secret - Bí mật webhook tùy chọn để bảo vệ payload webhook - String

• list_webhooks - Liệt kê tất cả webhook của tổ chức hoặc dự án SonarQube. Yêu cầu quyền 'Administer' đối với dự án được chỉ định hoặc quyền 'Administer' toàn cục.

  • organization - Khóa tổ chức SonarQube Cloud - Optional String, Cloud only
  • projectKey - Khóa dự án tùy chọn để liệt kê các webhook dành riêng cho dự án - String

Bổ sung ngữ cảnh

# 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"
      }
    }
  }
}

Mức độ sẵn sàng cho tác tử

Lưu ý: Các công cụ Mức độ sẵn sàng cho tác tử chỉ khả dụng trên SonarQube Cloud và yêu cầu bật tính năng này cho tổ chức của bạn.

Cờ tính năng được kiểm tra khi khởi động ở chế độ stdio. Qua HTTP/HTTPS, hãy thêm agentic-readiness vào SONARQUBE_TOOLSETS của máy chủ để bật các công cụ.

• start_agentic_readiness_assessment - Bắt đầu đánh giá mức độ sẵn sàng cho tác tử của một dự án. Trả về ngay với trạng thái PENDING và một assessmentId. Dùng get_agentic_readiness_assessment để thăm dò kết quả.

  • projectKey - Khóa dự án - Chuỗi bắt buộc (Bị bỏ qua khi đã xác định SONARQUBE_PROJECT_KEY)
  • branch - Nhánh cần đánh giá. Bỏ qua để dùng nhánh mặc định của dự án - String

• get_agentic_readiness_assessment - Truy xuất kết quả đánh giá. Gọi lại với cùng assessmentId cho đến khi trạng thái là COMPLETED, FAILED hoặc INTERRUPTED. Khi hoàn tất, trả về cấp độ tổng thể và phân tích theo từng trụ cột, kèm các hành động được đề xuất và bằng chứng.

  • assessmentId - ID đánh giá do start_agentic_readiness_assessment trả về - Chuỗi bắt buộc

• list_agentic_readiness_assessments - Liệt kê tất cả đánh giá của một dự án, mới nhất trước. Dùng get_agentic_readiness_assessment để xem kết quả đầy đủ ở cấp độ trụ cột.

  • projectKey - Khóa dự án cần liệt kê đánh giá - Chuỗi bắt buộc (Bị bỏ qua khi đã xác định SONARQUBE_PROJECT_KEY)
  • branch - Lọc đánh giá theo tên nhánh. Bỏ qua để liệt kê đánh giá của tất cả các nhánh - String
  • pageIndex - Chỉ mục trang bắt đầu từ 1 (mặc định: 1) - Number
  • pageSize - Số mục trên mỗi trang, tối đa 100 (mặc định: 50) - Number

Kiến trúc

Lưu ý: Bật các công cụ này bằng SONARQUBE_TOOLSETS=architecture ở chế độ stdio hoặc HTTP/HTTPS. SonarQube Cloud yêu cầu gói Team hoặc Enterprise. SonarQube Server yêu cầu phiên bản 2026.6 trở lên và Developer edition trở lên; các công cụ này không khả dụng trên phiên bản cũ hơn hoặc Community Build. Xem quy trình và cách khôi phục kiến trúc.

• architecture_get - Đọc các phần phụ thuộc hiện tại, kiến trúc dự kiến, chỉ thị dự án hoặc Findings (các sai lệch, lỗi và điểm yếu).

  • target - current, intended, directives hoặc findings; khả năng sử dụng tùy thuộc vào bản dựng MCP và Server - Enum bắt buộc
  • projectKey - Khóa dự án - Chuỗi bắt buộc (Bị bỏ qua khi đã xác định SONARQUBE_PROJECT_KEY)
  • organization - Khóa tổ chức SonarQube Cloud khi chưa được cấu hình - Chuỗi tùy chọn, chỉ dành cho Cloud
  • component - Khóa nút hiện tại chính xác hoặc đường dẫn nhóm dự kiến; mặc định là cấp cao nhất nếu bỏ qua - String
  • depth - Chỉ dành cho hiện tại/dự kiến: số cấp bên dưới điểm bắt đầu; mặc định là 1 đối với hiện tại, tất cả đối với dự kiến - Number
  • language - Chỉ dành cho hiện tại/dự kiến/findings: java, cs, js, ts hoặc py - Enum
  • directiveId - Chỉ thị đầy đủ theo UUID, bao gồm mô tả; dùng thay cho phân trang - String
  • category / type - Chỉ dành cho Findings: lọc sai lệch, lỗi hoặc điểm yếu theo loại được công bố - Enum
  • pageIndex - Chỉ thị/Findings: chỉ mục trang bắt đầu từ 1 (mặc định: 1) - Number
  • pageSize - Chỉ thị: bản tóm tắt, mặc định/tối đa 50. Findings: mặc định 50, tối đa 1000; 0 chỉ đếm - Number

• architecture_set - Thay thế toàn bộ kiến trúc dự kiến hoặc tạo, cập nhật và xóa chỉ thị dự án. Khả dụng trên các bản dựng Cloud và Server được hỗ trợ khi bật quyền ghi.

  • target - intended hoặc directives - Enum bắt buộc
  • projectKey - Khóa dự án - Chuỗi bắt buộc (Bị bỏ qua khi đã xác định SONARQUBE_PROJECT_KEY)
  • organization - Khóa tổ chức SonarQube Cloud khi chưa được cấu hình - Chuỗi tùy chọn, chỉ dành cho Cloud
  • model - Chuỗi JSON: bản xuất dự kiến đầy đủ hoặc mảng models (nội dung bị lược bỏ sẽ bị xóa), hoặc các thay đổi chỉ thị với các mảng create, update và delete - Chuỗi bắt buộc
  • dryRun - true để xem trước, false để áp dụng - Boolean bắt buộc
  • revision - Chỉ dành cho kiến trúc dự kiến: bản sửa đổi từ architecture_get; mặc định là bản sửa đổi của bản xuất đầy đủ. Bắt buộc khi áp dụng thao tác xóa - String

Prompt mẫu

Sau khi thiết lập SonarQube MCP Server, dưới đây là một số prompt mẫu cho các tình huống thực tế thường gặp:

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?

Build

Ưu tiên sử dụng ảnh vùng chứa sonarsource/sonarqube-mcp.

Để chạy máy chủ dưới dạng JAR độc lập mà không cần Docker, hãy tải bản phát hành dựng sẵn từ kho nhị phân SonarSource. Mỗi phiên bản phát hành đều được xuất bản tại đó dưới dạng sonarqube-mcp-server-<version>.jar (ví dụ: 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

Khắc phục sự cố

Theo mặc định, nhật ký ứng dụng được ghi vào tệp STORAGE_PATH/logs/mcp.log. Để tắt hoàn toàn việc ghi nhật ký vào tệp, hãy đặt SONARQUBE_LOG_TO_FILE_DISABLED=true.

Các vấn đề thường gặp

"Phiên bản máy chủ SonarQube không được hỗ trợ"

Máy chủ MCP kiểm tra phiên bản SonarQube Server được kết nối khi khởi động. Nếu phiên bản của máy chủ cũ hơn 2025.1 (SQS) hoặc 25.1 (SQCB), quá trình khởi động sẽ thất bại với thông báo:

SonarQube server version is not supported, minimal version is SQS 2025.1 or SQCB 25.1

Giải pháp: Nâng cấp SonarQube Server lên bản phát hành được hỗ trợ. Kiểm tra này chỉ áp dụng khi kết nối với SonarQube Server (SONARQUBE_URL mà không có SONARQUBE_ORG), không áp dụng cho SonarQube Cloud.

"Tính năng không hoạt động" hoặc "Thiếu công cụ/chức năng"

Có thể bạn đang chạy ảnh Docker đã lỗi thời. Docker lưu ảnh cục bộ vào bộ nhớ đệm nên bạn sẽ không tự động nhận được bản cập nhật.

Giải pháp: Cập nhật lên phiên bản mới nhất:

docker pull sonarsource/sonarqube-mcp

Sau khi tải ảnh mới nhất, hãy khởi động lại ứng dụng MCP để sử dụng phiên bản đã cập nhật.

Bạn cũng có thể thêm cờ --pull=always vào lệnh docker run để luôn kiểm tra và tải phiên bản mới nhất:

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

"Tôi muốn ghim vào một phiên bản cụ thể"

Duyệt các thẻ hiện có tại sonarsource/sonarqube-mcp và tham chiếu phiên bản bạn muốn:

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

Trong cấu hình ứng dụng MCP, hãy dùng sonarsource/sonarqube-mcp:<version> thay cho sonarsource/sonarqube-mcp và xóa --pull=always để Docker không âm thầm nâng cấp ảnh.

Dữ liệu và phép đo từ xa

Máy chủ này thu thập dữ liệu sử dụng ẩn danh và gửi đến SonarSource để giúp cải thiện sản phẩm. Không có mã nguồn hoặc địa chỉ IP nào được thu thập, và SonarSource không chia sẻ dữ liệu với bất kỳ ai khác. Có thể tắt việc thu thập dữ liệu đo từ xa bằng thuộc tính hệ thống hoặc biến môi trường sau: TELEMETRY_DISABLED=true. Nhấp vào đây để xem mẫu dữ liệu được thu thập.

Giấy phép

Bản quyền 2025 SonarSource.

Được cấp phép theo SONAR Source-Available License v1.0. Việc sử dụng SonarQube MCP Server tuân thủ tài liệu này là Mục đích Không Cạnh tranh và do đó được SSAL cho phép.

Việc bạn sử dụng SonarQube thông qua MCP chịu sự điều chỉnh của Điều khoản dịch vụ SonarQube Cloud hoặc Điều khoản và điều kiện SonarQube Server, bao gồm việc chỉ sử dụng Dữ liệu kết quả cho mục đích phát triển phần mềm nội bộ của bạn.