CircleCI
chính thứcCho phép AI Agent sửa lỗi build từ CircleCI.
Bạn có thể làm gì với CircleCI MCP?
- Xác thực cấu hình CircleCI — Yêu cầu xác thực
.circleci/config.ymlcủa bạn để kiểm tra lỗi cú pháp và ngữ nghĩa thông quaconfig_helper. - Lấy trạng thái pipeline — Kiểm tra trạng thái pipeline mới nhất cho một nhánh bằng
get_latest_pipeline_status. - Kích hoạt và chạy lại pipeline — Bắt đầu một pipeline mới với
run_pipelinehoặc chạy lại một workflow từ đầu hoặc từ job thất bại quarerun_workflow. - Điều tra lỗi build — Truy xuất nhật ký lỗi chi tiết bằng
get_build_failure_logsvà kết quả kiểm thử quaget_job_test_results. - Tìm kiếm test không ổn định — Xác định các test không ổn định bằng cách phân tích lịch sử thực thi test sử dụng
find_flaky_tests. - Phân tích mức sử dụng và chi phí — Tải dữ liệu sử dụng bằng
download_usage_api_datavà tìm các lớp tài nguyên ít được sử dụng quafind_underused_resource_classes.
Tài liệu
[!IMPORTANT] Gói này đã bị ngừng phát triển. Vui lòng di chuyển sang giải pháp khác.
@circleci/mcp-server-circlecikhông còn nhận được các cải tiến tính năng. Hãy sử dụng MCP server được lưu trữ của CircleCI hoặc CircleCI CLI MCP để thay thế — xem tổng quan về CircleCI MCP.Kho lưu trữ này sẽ được lưu trữ dưới dạng lưu trữ. Các phiên bản hiện có vẫn có thể cài đặt từ npm, nhưng việc chạy một máy chủ không được bảo trì giữ CircleCI Personal API Token không được khuyến nghị.
Nếu bạn đang chạy transport từ xa tự quản lý (
start=remote), hãy di chuyển trước: máy chủ được lưu trữ là sự thay thế trực tiếp và loại bỏ nhu cầu vận hành một dịch vụ hướng mạng làm trung gian cho token của tổ chức bạn.
CircleCI MCP Server
Model Context Protocol (MCP) là một giao thức mới, được chuẩn hóa để quản lý ngữ cảnh giữa các mô hình ngôn ngữ lớn (LLM) và các hệ thống bên ngoài. Trong kho lưu trữ này, chúng tôi cung cấp một MCP Server cho CircleCI.
Sử dụng Cursor, Windsurf, Copilot, Claude hoặc bất kỳ máy khách tương thích MCP nào để tương tác với CircleCI bằng ngôn ngữ tự nhiên — mà không cần rời khỏi IDE của bạn.
Công cụ
| Công cụ | Mô tả |
|---|---|
config_helper | Xác thực và nhận hướng dẫn cho cấu hình CircleCI của bạn |
download_usage_api_data | Tải xuống dữ liệu sử dụng từ CircleCI Usage API |
find_flaky_tests | Xác định các bài kiểm tra không ổn định bằng cách phân tích lịch sử thực thi kiểm thử |
find_underused_resource_classes | Tìm các công việc sử dụng tài nguyên tính toán chưa hết công suất |
get_build_failure_logs | Truy xuất nhật ký lỗi chi tiết từ các bản dựng CircleCI |
get_job_test_results | Truy xuất siêu dữ liệu và kết quả kiểm thử cho các công việc CircleCI |
get_latest_pipeline_status | Lấy trạng thái của pipeline mới nhất cho một nhánh |
list_artifacts | Liệt kê các artifact được tạo bởi một công việc CircleCI |
list_component_versions | Liệt kê tất cả các phiên bản cho một thành phần CircleCI |
list_followed_projects | Liệt kê tất cả các dự án CircleCI bạn đang theo dõi |
rerun_workflow | Chạy lại một workflow từ đầu hoặc từ công việc thất bại |
run_pipeline | Kích hoạt một pipeline để chạy |
run_rollback_pipeline | Kích hoạt rollback cho một dự án |
Cài đặt
Triển khai nhóm / tập trung: Để chạy một máy chủ từ xa dùng chung cho tổ chức của bạn (Kubernetes, Docker, v.v.) với token CircleCI riêng cho từng nhà phát triển hoặc dùng chung, hãy xem Self-Managed Remote MCP Server.
Cursor
Điều kiện tiên quyết:
- CircleCI Personal API token (tìm hiểu thêm)
- NPX: Node.js >= v18 và pnpm
- Docker: Docker
Sử dụng NPX trong MCP Server cục bộ
Thêm nội dung sau vào cấu hình MCP của Cursor:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci@latest"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}
CIRCLECI_BASE_URLlà tùy chọn — chỉ bắt buộc đối với khách hàng on-prem.MAX_MCP_OUTPUT_LENGTHlà tùy chọn — độ dài đầu ra tối đa cho phản hồi MCP (mặc định: 50000).
Sử dụng Docker trong MCP Server cục bộ
Thêm nội dung sau vào cấu hình MCP của Cursor:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"-e",
"MAX_MCP_OUTPUT_LENGTH",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server. Sử dụng cấu hình máy khách theo từng người dùng và thêm vào cấu hình MCP của Cursor (Cursor Settings → MCP).
VS Code
Điều kiện tiên quyết:
- CircleCI Personal API token (tìm hiểu thêm)
- NPX: Node.js >= v18 và pnpm
- Docker: Docker
Sử dụng NPX trong MCP Server cục bộ
Thêm nội dung sau vào .vscode/mcp.json trong dự án của bạn:
{
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
},
{
"type": "promptString",
"id": "circleci-base-url",
"description": "CircleCI Base URL",
"default": "https://circleci.com"
}
],
"servers": {
"circleci-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci@latest"],
"env": {
"CIRCLECI_TOKEN": "${input:circleci-token}",
"CIRCLECI_BASE_URL": "${input:circleci-base-url}"
}
}
}
}
💡 Các đầu vào được nhắc khi máy chủ khởi động lần đầu, sau đó được VS Code lưu trữ an toàn.
Sử dụng Docker trong MCP Server cục bộ
Thêm nội dung sau vào .vscode/mcp.json trong dự án của bạn:
{
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
},
{
"type": "promptString",
"id": "circleci-base-url",
"description": "CircleCI Base URL",
"default": "https://circleci.com"
}
],
"servers": {
"circleci-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "${input:circleci-token}",
"CIRCLECI_BASE_URL": "${input:circleci-base-url}"
}
}
}
}
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server. Sử dụng cấu hình máy khách theo từng người dùng trong .vscode/mcp.json.
Claude Desktop
Điều kiện tiên quyết:
- CircleCI Personal API token (tìm hiểu thêm)
- NPX: Node.js >= v18 và pnpm
- Docker: Docker
Sử dụng NPX trong MCP Server cục bộ
Thêm nội dung sau vào claude_desktop_config.json của bạn:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci@latest"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}
Sử dụng Docker trong MCP Server cục bộ
Thêm nội dung sau vào claude_desktop_config.json của bạn:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"-e",
"MAX_MCP_OUTPUT_LENGTH",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server. Tạo một script bọc như được minh họa trong Claude Desktop và máy khách CLI, sau đó trỏ claude_desktop_config.json của bạn vào script đó.
Để tìm hoặc tạo tệp cấu hình của bạn, hãy mở cài đặt Claude Desktop, nhấp vào Developer trong thanh bên trái, sau đó nhấp vào Edit Config. Tệp cấu hình nằm tại:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Để biết thêm thông tin: https://modelcontextprotocol.io/quickstart/user
Claude Code
Điều kiện tiên quyết:
- CircleCI Personal API token (tìm hiểu thêm)
- NPX: Node.js >= v18 và pnpm
- Docker: Docker
Sử dụng NPX trong MCP Server cục bộ
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest
Sử dụng Docker trong MCP Server cục bộ
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci/mcp-server-circleci
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server và phần thiết lập máy khách Claude Code tại đó.
Windsurf
Điều kiện tiên quyết:
- CircleCI Personal API token (tìm hiểu thêm)
- NPX: Node.js >= v18 và pnpm
- Docker: Docker
Sử dụng NPX trong MCP Server cục bộ
Thêm nội dung sau vào mcp_config.json của Windsurf:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci@latest"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}
Sử dụng Docker trong MCP Server cục bộ
Thêm nội dung sau vào mcp_config.json của Windsurf:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"-e",
"MAX_MCP_OUTPUT_LENGTH",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server. Sử dụng cấu hình máy khách theo từng người dùng trong mcp_config.json của Windsurf.
Để biết thêm thông tin: https://docs.windsurf.com/windsurf/mcp
Amazon Q Developer CLI
Điều kiện tiên quyết:
Cấu hình máy khách MCP trong Amazon Q Developer được lưu trữ ở định dạng JSON trong một tệp có tên mcp.json. Hai cấp độ cấu hình được hỗ trợ:
- Toàn cục:
~/.aws/amazonq/mcp.json— áp dụng cho tất cả các workspace - Workspace:
.amazonq/mcp.json— dành riêng cho workspace hiện tại
Nếu cả hai tệp tồn tại, nội dung của chúng sẽ được hợp nhất. Trong trường hợp xung đột, cấu hình workspace được ưu tiên.
Sử dụng NPX trong MCP Server cục bộ
Chỉnh sửa ~/.aws/amazonq/mcp.json hoặc tạo .amazonq/mcp.json với nội dung sau:
{
"mcpServers": {
"circleci-local": {
"command": "npx",
"args": [
"-y",
"@circleci/mcp-server-circleci@latest"
],
"env": {
"CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
},
"timeout": 60000
}
}
}
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server. Sử dụng script bọc như được minh họa trong Claude Desktop và máy khách CLI, sau đó đăng ký nó với q mcp add.
Amazon Q Developer trong IDE
Điều kiện tiên quyết:
Sử dụng NPX trong MCP Server cục bộ
Chỉnh sửa ~/.aws/amazonq/mcp.json hoặc tạo .amazonq/mcp.json với nội dung sau:
{
"mcpServers": {
"circleci-local": {
"command": "npx",
"args": [
"-y",
"@circleci/mcp-server-circleci@latest"
],
"env": {
"CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
},
"timeout": 60000
}
}
}
Sử dụng Self-Managed Remote MCP Server
Xem Self-Managed Remote MCP Server. Sử dụng script bọc như được minh họa trong Claude Desktop và máy khách CLI, sau đó thêm nó qua giao diện cấu hình MCP:
- Truy cập giao diện cấu hình MCP
- Chọn ký hiệu +
- Chọn phạm vi: global hoặc local
- Nhập tên (ví dụ:
circleci-remote-mcp) - Chọn giao thức truyền tải: stdio
- Nhập đường dẫn lệnh đến script của bạn
- Nhấp Save
Smithery
Để cài đặt CircleCI MCP Server cho Claude Desktop tự động qua Smithery:
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
Self-Managed Remote MCP Server
Chạy MCP server tập trung (ví dụ trên Kubernetes hoặc Docker) để nhóm của bạn dùng chung một triển khai. Chọn cách các nhà phát triển xác thực:
Chọn chế độ triển khai
| Chế độ | Khi nào sử dụng | Thiết lập máy chủ | Thiết lập máy khách | Nhật ký kiểm toán CircleCI |
|---|---|---|---|---|
| Token theo từng người dùng (khuyến nghị) | Nhóm có Personal API Token hỗ trợ SSO | REQUIRE_REQUEST_TOKEN=true, không cần PAT máy chủ | Mỗi nhà phát triển chuyển tiếp PAT của họ | Theo từng nhà phát triển |
| Token dùng chung (tạm thời) | Triển khai nhanh, danh tính dịch vụ đơn lẻ chấp nhận được | CIRCLECI_TOKEN trên máy chủ, REQUIRE_REQUEST_TOKEN=false (từ chối rõ ràng) | Không cần header xác thực | Một danh tính dùng chung duy nhất |
Bảo mật: Xác thực yêu cầu được bật theo mặc định trong chế độ từ xa. Chế độ token dùng chung vô hiệu hóa nó (
REQUIRE_REQUEST_TOKEN=false), khiến mọi người gọi có thể hoạt động với danh tínhCIRCLECI_TOKENcủa máy chủ mà không cần thông tin xác thực — bao gồm cả việc kích hoạt pipeline với cấu hình tùy ý. Chỉ bật chế độ này trên mạng bạn hoàn toàn tin tưởng, và ưu tiên token theo từng người dùng trong các trường hợp khác. Kết thúc TLS tại một ingress cung cấp mã hóa, không phải xác thực.Vì sự kết hợp đó không an toàn trên giao diện công khai, máy chủ từ chối khởi động khi
REQUIRE_REQUEST_TOKEN=falseđược kết hợp với địa chỉ bind không phải loopback, trừ khi bạn chấp nhận rủi ro một cách rõ ràng bằngMCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true. Kiểm traHost/Originkhông phải là sự thay thế cho xác thực — xem bảo vệ chống DNS-rebinding bên dưới.
1. Triển khai máy chủ
Cả hai chế độ đều sử dụng chế độ HTTP từ xa (start=remote). Xuất bản cổng 8000 (hoặc cổng bạn chọn).
Token theo từng người dùng (khuyến nghị) — truy cập qua mcp-remote từ localhost:
docker run --rm -p 8000:8000 \
-e start=remote \
-e port=8000 \
-e REQUIRE_REQUEST_TOKEN=true \
circleci/mcp-server-circleci
Token theo từng người dùng (khuyến nghị) — truy cập qua mcp-remote từ một hostname công khai:
docker run --rm -p 8000:8000 \
-e start=remote \
-e port=8000 \
-e REQUIRE_REQUEST_TOKEN=true \
-e MCP_ALLOWED_HOSTS=my-mcp.example.com \
circleci/mcp-server-circleci
Token dùng chung (tạm thời) — truy cập qua mcp-remote từ một hostname công khai:
Vì chế độ này phục vụ PAT của tổ chức cho bất kỳ người gọi nào mà không cần thông tin xác thực, nó chỉ được chạy ở nơi cổng được xuất bản không thể truy cập từ các mạng không đáng tin cậy, và bạn phải xác nhận điều đó một cách rõ ràng nếu không máy chủ sẽ từ chối khởi động:
docker run --rm -p 8000:8000 \
-e start=remote \
-e port=8000 \
-e CIRCLECI_TOKEN=your-shared-circleci-pat \
-e REQUIRE_REQUEST_TOKEN=false \
-e MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true \
-e MCP_ALLOWED_HOSTS=my-mcp.example.com \
circleci/mcp-server-circleci
Ưu tiên đặt xác thực phía trước cổng — một ingress yêu cầu SSO, mTLS hoặc API key — hoặc chuyển sang token theo từng người dùng ở trên.
Biến môi trường:
| Biến | Mô tả |
|---|---|
start=remote | Khởi động máy chủ MCP HTTP+SSE thay vì stdio |
port | Cổng lắng nghe bên trong container (mặc định: 8000) |
REQUIRE_REQUEST_TOKEN | Từ chối các yêu cầu không có header Authorization: Bearer hoặc Circle-Token. Mặc định là bắt buộc; đặt REQUIRE_REQUEST_TOKEN=false để cho phép các yêu cầu không xác thực (chế độ token dùng chung) |
CIRCLECI_TOKEN | PAT dự phòng dùng chung cho mọi yêu cầu khi không gửi header theo từng người dùng |
CIRCLECI_BASE_URL | Tùy chọn — chỉ bắt buộc đối với on-prem (mặc định: https://circleci.com) |
DISABLE_TELEMETRY=true | Từ chối xuất số liệu sử dụng |
MCP_ALLOWED_HOSTS | Danh sách phân tách bằng dấu phẩy các giá trị header Host bổ sung được phép (ví dụ: my-mcp.example.com,my-mcp.example.com:443). Tên máy chủ loopback luôn được phép. Bắt buộc đối với mọi triển khai không dùng loopback. |
MCP_ALLOWED_ORIGINS | Danh sách phân tách bằng dấu phẩy các giá trị header Origin bổ sung được phép (ví dụ: https://my-app.example.com). Origin loopback luôn được phép. Chỉ cần khi trình duyệt truy cập trực tiếp máy chủ này (không qua mcp-remote). |
MCP_BIND_HOST | Giao diện mạng để liên kết (mặc định: 0.0.0.0). Đặt thành 127.0.0.1 để giới hạn chỉ dùng loopback (không tương thích với ánh xạ cổng Docker -p). |
MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS | Bắt buộc (=true) để khởi động với REQUIRE_REQUEST_TOKEN=false trên địa chỉ bind không dùng loopback. Xác nhận rằng mọi đối tác có thể truy cập cổng sẽ đóng vai trò danh tính CIRCLECI_TOKEN của máy chủ mà không cần thông tin xác thực. Không có tác dụng khi bắt buộc token yêu cầu. |
MCP_FILE_OUTPUT_ROOTS | Danh sách phân tách bằng dấu phẩy các thư mục bổ sung mà các công cụ đọc/ghi tệp có thể sử dụng (ví dụ: /srv/reports,/data/exports). Thư mục làm việc, thư mục home và thư mục temp luôn được phép. Xem ghi chú bên dưới. |
Vị trí xuất tệp (áp dụng cho cả transport stdio và remote): Các công cụ chấp nhận đường dẫn hệ thống tệp —
get_build_failure_logs(outputDir),download_usage_api_data(outputDir) vàfind_underused_resource_classes(csvFilePath) — chỉ được phép đọc và ghi bên trong thư mục làm việc của máy chủ, thư mục home của người dùng và thư mục temp hệ thống. Trong các thư mục gốc đó, các thư mục cấu hình ẩn (~/.ssh,~/.aws,~/.config,.git, …),node_modulesvà các thư mục launch-agent bị từ chối, cũng như các symlink trỏ đến bên ngoài các thư mục gốc được phép. Các thư mục hệ thống (/etc,/usr,/bin,/System,/Library,%SystemRoot%, …) bị từ chối vô điều kiện và không thể bật lại. Các tệp đầu ra không bao giờ được ghi qua symlink.Nếu bản checkout của bạn nằm ngoài các thư mục gốc đó —
/workspacetrong container,/srv,/opt, một ổ đĩa phụ như/Volumes/work— hãy đặtMCP_FILE_OUTPUT_ROOTSthành thư mục đó, nếu không các đường dẫn đó sẽ bị từ chối. Đối với máy chủ stdio, thư mục làm việc thường đã là thư mục gốc của dự án, nên không cần cấu hình. Điều này quan trọng nhất đối với transport remote, nơi các đường dẫn đến từ máy khách mạng thay vì người dùng cục bộ.
Bảo vệ chống DNS-rebinding (không phải xác thực): Transport remote xác thực header
Hosttrên mọi yêu cầu/mcp. Theo mặc định chỉ chấp nhận các địa chỉ loopback (localhost,127.0.0.1,[::1]). Các triển khai công khai phải đặtMCP_ALLOWED_HOSTSthành tên máy chủ mà máy khách sử dụng, nếu không mọi yêu cầu/mcpsẽ nhận được403 Forbidden. Điểm cuối kiểm tra sức khỏe/pingkhông được bảo vệ để các probe của bộ cân bằng tải tiếp tục hoạt động bất kểHost.Header
Origin(do trình duyệt gửi) cũng được xác thực khi có mặt. Các máy khách không phải trình duyệt nhưmcp-remotekhông bao giờ gửiOrigin, vì vậy chúng không bị ảnh hưởng bởi kiểm tra này.Kiểm tra này không phải là kiểm soát truy cập và không được dựa vào như vậy. Cả hai header đều do người gọi chọn, vì vậy bất kỳ máy khách không phải trình duyệt nào — curl, script, socket thô — đều có thể gửi
Hostđược phép và bỏ quaOriginđể vượt qua kiểm tra. Mục đích duy nhất của nó là ngăn trình duyệt bị điều hướng đến máy chủ bởi DNS do kẻ tấn công kiểm soát, tức là mối đe dọa DNS-rebinding. Xác thực người gọi là nhiệm vụ củaREQUIRE_REQUEST_TOKEN(hoặc một proxy xác thực phía trước cổng). Yêu cầu headerOriginsẽ phá vỡ mọi máy khách CLI hợp lệ trong khi không chặn được kẻ tấn công nào.Phía sau reverse proxy: Nếu proxy của bạn viết lại
Hostthành địa chỉ backend (mặc định của nginx), hãy thêmproxy_set_header Host $host;để chuyển tên máy chủ gốc qua, sau đó đặtMCP_ALLOWED_HOSTSthành tên máy chủ công khai đó. Ngoài ra, bạn có thể đặtMCP_ALLOWED_HOSTSthành bất kỳ tên máy chủ nào mà proxy chuyển tiếp.
Máy chủ chấp nhận token theo từng yêu cầu qua:
Authorization: Bearer <circleci-pat>Circle-Token: <circleci-pat>
Nếu máy khách gửi token qua header, token đó sẽ được ưu tiên hơn CIRCLECI_TOKEN trên máy chủ.
Số liệu telemetry được ghi trong một yêu cầu sẽ được xuất bằng cùng token với yêu cầu đó.
2. Cấu hình máy khách
Hầu hết máy khách MCP chỉ hỗ trợ các tiến trình cục bộ (stdio). Sử dụng mcp-remote, một cầu nối stdio-sang-HTTP của bên thứ ba, để kết nối chúng với máy chủ từ xa của bạn.
Lược đồ URL: Sử dụng
http://localhost:8000/mcpvới--allow-httpđể kiểm thử cục bộ. Trong sản xuất, hãy kết thúc TLS tại ingress/bộ cân bằng tải của bạn và sử dụnghttps://your-host/mcpmà không có--allow-http.
Windows: Tránh khoảng trắng xung quanh dấu hai chấm trong giá trị
--header. Đặt toàn bộ giá trịBearer <token>trong một biến môi trường.
Bảo mật: Các ví dụ sử dụng
npxđể thuận tiện. Đối với triển khai sản xuất hoặc triển khai theo nhóm, hãy ghim một phiên bản cụ thể trong cấu hình MCP của bạn (ví dụmcp-remote@0.1.38thay vìmcp-remote). Không sử dụng các phiên bản dưới0.1.16(CVE-2025-6514).
Cấu hình máy khách: token theo từng người dùng
Mỗi nhà phát triển chuyển tiếp Token API Cá nhân CircleCI của riêng họ trên mọi yêu cầu:
{
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
}
],
"mcpServers": {
"circleci-mcp-server-remote": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp",
"--allow-http",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer ${input:circleci-token}"
}
}
}
}
Thay http://localhost:8000/mcp bằng URL máy chủ của nhóm bạn. Cursor và VS Code hỗ trợ lời nhắc ${input:...}; các máy khách khác có thể đặt AUTH_HEADER trực tiếp.
Cấu hình máy khách: token dùng chung
Khi máy chủ có CIRCLECI_TOKEN được đặt và được khởi động với REQUIRE_REQUEST_TOKEN=false (xác thực yêu cầu được bật theo mặc định và phải được tắt một cách tường minh, và bind không dùng loopback cũng yêu cầu MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true), máy khách không cần gửi token:
{
"mcpServers": {
"circleci-mcp-server-remote": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp",
"--allow-http"
]
}
}
}
Claude Desktop và máy khách CLI
Tạo một script bọc (ví dụ: circleci-remote-mcp.sh):
#!/bin/bash
export AUTH_HEADER="Bearer your-circleci-token"
npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"
Làm cho nó có thể thực thi (chmod +x circleci-remote-mcp.sh), sau đó tham chiếu nó từ cấu hình MCP của bạn:
{
"mcpServers": {
"circleci-remote-mcp-server": {
"command": "/full/path/to/circleci-remote-mcp.sh"
}
}
}
Claude Code
claude mcp add circleci-mcp-server \
-e AUTH_HEADER="Bearer your-circleci-token" \
-- npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"
Bỏ qua --header và AUTH_HEADER khi sử dụng máy chủ token dùng chung.
3. Xác minh triển khai
# Health check (no auth required)
curl http://localhost:8000/ping
# Should return 401 when REQUIRE_REQUEST_TOKEN=true and no token is sent
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# Should return 200 with a valid Bearer token and MCP Accept headers
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer your-circleci-pat" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
Demo
Xem nó hoạt động
Ví dụ: "Tìm pipeline thất bại mới nhất trên nhánh của tôi và lấy log" — xem wiki để biết thêm ví dụ.
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
Chi tiết Công cụ
config_helper
Hỗ trợ các tác vụ cấu hình CircleCI bằng cách cung cấp hướng dẫn và xác thực.
- Xác thực
.circleci/config.ymlcủa bạn về lỗi cú pháp và ngữ nghĩa - Cung cấp kết quả xác thực chi tiết và khuyến nghị cấu hình
- Ví dụ: "Xác thực cấu hình CircleCI của tôi"
download_usage_api_data
Tải dữ liệu sử dụng từ CircleCI Usage API cho một tổ chức nhất định. Chấp nhận đầu vào ngày linh hoạt (ví dụ: "Tháng 3 năm 2025" hoặc "tháng trước"). Chỉ dành cho cloud.
Tùy chọn 1: Bắt đầu một công việc xuất mới bằng cách cung cấp:
orgId,startDate,endDate(tối đa 32 ngày),outputDir
Tùy chọn 2: Kiểm tra/tải một công việc xuất hiện có bằng cách cung cấp:
orgId,jobId,outputDir
Trả về tệp CSV với dữ liệu sử dụng CircleCI cho khung thời gian đã chỉ định.
[!NOTE] Dữ liệu sử dụng có thể được đưa vào công cụ
find_underused_resource_classesđể phân tích tối ưu hóa chi phí.
find_flaky_tests
Xác định các bài kiểm tra không ổn định (flaky) trong dự án CircleCI của bạn bằng cách phân tích lịch sử thực thi bài kiểm tra. Tận dụng tính năng phát hiện bài kiểm tra không ổn định trong CircleCI.
Công cụ này có thể được sử dụng theo ba cách:
-
Sử dụng Project Slug (Khuyến nghị):
- Đầu tiên dùng
list_followed_projectsđể lấy các dự án của bạn, sau đó: - Ví dụ: "Lấy các bài kiểm tra không ổn định cho my-project"
- Đầu tiên dùng
-
Sử dụng URL dự án CircleCI:
- Ví dụ: "Tìm các bài kiểm tra không ổn định trong https://app.circleci.com/pipelines/github/org/repo"
-
Sử dụng bối cảnh dự án cục bộ:
- Hoạt động từ không gian làm việc cục bộ của bạn bằng cách cung cấp thư mục gốc không gian làm việc và URL git remote
- Ví dụ: "Tìm các bài kiểm tra không ổn định trong dự án hiện tại của tôi"
Chế độ đầu ra:
- Văn bản (mặc định): Trả về chi tiết bài kiểm tra không ổn định ở định dạng văn bản
- Tệp (yêu cầu biến môi trường
FILE_OUTPUT_DIRECTORY): Tạo một thư mục chứa chi tiết bài kiểm tra không ổn định
find_underused_resource_classes
Phân tích tệp CSV dữ liệu sử dụng CircleCI để tìm các công việc có mức sử dụng CPU/RAM trung bình hoặc tối đa dưới ngưỡng nhất định (mặc định: 40%).
Cung cấp tệp CSV thu được từ download_usage_api_data.
Trả về danh sách markdown các công việc được sử dụng không đúng mức được nhóm theo dự án và workflow — hữu ích để xác định các cơ hội tối ưu hóa chi phí.
get_build_failure_logs
Truy xuất log lỗi chi tiết từ các bản build CircleCI. Công cụ này có thể được sử dụng theo ba cách:
-
Sử dụng Project Slug và Nhánh (Khuyến nghị):
- Đầu tiên dùng
list_followed_projectsđể lấy các dự án của bạn, sau đó: - Ví dụ: "Lấy các lỗi build cho my-project trên nhánh main"
- Đầu tiên dùng
-
Sử dụng URL CircleCI:
- Cung cấp trực tiếp URL công việc thất bại hoặc URL pipeline
- Ví dụ: "Lấy log từ https://app.circleci.com/pipelines/github/org/repo/123"
-
Sử dụng bối cảnh dự án cục bộ:
- Hoạt động từ không gian làm việc cục bộ của bạn bằng cách cung cấp thư mục gốc không gian làm việc, URL git remote và tên nhánh
- Ví dụ: "Tìm pipeline thất bại mới nhất trên nhánh hiện tại của tôi"
Công cụ trả về log được định dạng bao gồm:
- Tên công việc
- Chi tiết thực thi từng bước
- Thông báo lỗi và bối cảnh
get_job_test_results
Truy xuất siêu dữ liệu bài kiểm tra cho các công việc CircleCI, cho phép bạn phân tích kết quả bài kiểm tra mà không cần rời khỏi IDE. Công cụ này có thể được sử dụng theo ba cách:
-
Sử dụng Project Slug và Nhánh (Khuyến nghị):
- Ví dụ: "Lấy kết quả bài kiểm tra cho my-project trên nhánh main"
-
Sử dụng URL CircleCI:
- URL công việc:
https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 - URL workflow:
https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def - URL pipeline:
https://app.circleci.com/pipelines/github/org/repo/123
- URL công việc:
-
Sử dụng bối cảnh dự án cục bộ:
- Hoạt động từ không gian làm việc cục bộ của bạn bằng cách cung cấp thư mục gốc không gian làm việc, URL git remote và tên nhánh
Công cụ trả về:
- Tóm tắt tất cả bài kiểm tra (tổng, thành công, thất bại)
- Thông tin chi tiết về các bài kiểm tra thất bại: tên, lớp, tệp, thông báo lỗi, thời lượng
- Danh sách các bài kiểm tra thành công kèm thời gian
- Lọc theo kết quả bài kiểm tra
[!NOTE] Siêu dữ liệu bài kiểm tra phải được cấu hình trong cấu hình CircleCI của bạn. Xem Thu thập Dữ liệu Bài kiểm tra để biết hướng dẫn thiết lập.
get_latest_pipeline_status
Truy xuất trạng thái của pipeline mới nhất cho một nhánh cụ thể. Công cụ này có thể được sử dụng theo ba cách:
-
Sử dụng Project Slug và Branch (Khuyến nghị):
- Ví dụ: "Lấy trạng thái của pipeline mới nhất cho dự án của tôi trên nhánh main"
-
Sử dụng URL dự án CircleCI:
- Ví dụ: "Lấy trạng thái của pipeline mới nhất cho https://app.circleci.com/pipelines/github/org/repo"
-
Sử dụng ngữ cảnh dự án cục bộ:
- Hoạt động từ workspace cục bộ của bạn bằng cách cung cấp thư mục gốc workspace, URL git remote và tên nhánh
Ví dụ đầu ra:
---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress
list_artifacts
Truy xuất danh sách các artifact được tạo ra bởi một công việc CircleCI. Công cụ này có thể được sử dụng theo ba cách:
-
Sử dụng Project Slug và Branch (Khuyến nghị):
- Đầu tiên sử dụng
list_followed_projectsđể lấy danh sách dự án của bạn, sau đó: - Ví dụ: "Liệt kê artifact cho dự án của tôi trên nhánh main"
- Đầu tiên sử dụng
-
Sử dụng URL CircleCI:
- URL công việc:
https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789 - URL workflow:
https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def - URL pipeline:
https://app.circleci.com/pipelines/gh/organization/project/123
- URL công việc:
-
Sử dụng ngữ cảnh dự án cục bộ:
- Hoạt động từ workspace cục bộ của bạn bằng cách cung cấp thư mục gốc workspace, URL git remote và tên nhánh
Hữu ích cho:
- Tìm URL tải xuống cho các artifact xây dựng (tệp nhị phân, báo cáo, nhật ký)
- Kiểm tra những artifact nào được tạo ra bởi một lần chạy pipeline
list_component_versions
Liệt kê tất cả các phiên bản cho một thành phần CircleCI cụ thể trong một môi trường. Bao gồm trạng thái triển khai, thông tin commit và dấu thời gian.
Công cụ sẽ nhắc bạn chọn thành phần và môi trường nếu không được cung cấp.
Hữu ích cho:
- Xác định phiên bản nào hiện đang hoạt động
- Chọn phiên bản mục tiêu cho các thao tác khôi phục
- Lấy thông tin chi tiết triển khai (pipeline, workflow, job)
list_followed_projects
Liệt kê tất cả các dự án mà người dùng đang theo dõi trên CircleCI.
- Hiển thị tất cả các dự án bạn có quyền truy cập cùng với
projectSlugcủa chúng - Ví dụ: "Liệt kê các dự án CircleCI của tôi"
Ví dụ đầu ra:
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)
[!NOTE]
projectSlug(không phải tên dự án) là bắt buộc cho nhiều công cụ CircleCI khác.
rerun_workflow
Chạy lại một workflow từ điểm bắt đầu hoặc từ công việc thất bại.
Trả về ID của workflow mới được tạo và liên kết để theo dõi nó.
run_pipeline
Kích hoạt một pipeline để chạy. Công cụ này có thể được sử dụng theo ba cách:
-
Sử dụng Project Slug và Branch (Khuyến nghị):
- Ví dụ: "Chạy pipeline cho dự án của tôi trên nhánh main"
-
Sử dụng URL CircleCI:
- URL Pipeline, URL Workflow, URL Job hoặc URL Project kèm nhánh
- Ví dụ: "Chạy pipeline cho https://app.circleci.com/pipelines/github/org/repo/123"
-
Sử dụng ngữ cảnh dự án cục bộ:
- Hoạt động từ workspace cục bộ của bạn bằng cách cung cấp thư mục gốc workspace, URL git remote và tên nhánh
Công cụ trả về liên kết để theo dõi quá trình thực thi pipeline.
run_rollback_pipeline
Kích hoạt khôi phục cho một dự án CircleCI. Công cụ hướng dẫn bạn tương tác qua các bước:
- Chọn dự án — liệt kê các dự án đang theo dõi để bạn chọn
- Chọn môi trường — liệt kê các môi trường có sẵn (tự động chọn nếu chỉ có một)
- Chọn thành phần — liệt kê các thành phần có sẵn (tự động chọn nếu chỉ có một)
- Chọn phiên bản — hiển thị các phiên bản có sẵn; bạn chọn mục tiêu để khôi phục
- Phát hiện chế độ khôi phục — kiểm tra xem pipeline khôi phục đã được cấu hình chưa
- Thực hiện khôi phục — hai tùy chọn:
- Khôi phục Pipeline: kích hoạt pipeline khôi phục
- Chạy lại Workflow: chạy lại một workflow trước đó bằng ID workflow của nó
- Xác nhận — tóm tắt và xác nhận trước khi thực hiện
Xử lý sự cố
Sửa nhanh
Các vấn đề phổ biến nhất:
-
Xóa bộ nhớ cache gói:
npx clear-npx-cache npm cache clean --force -
Buộc phiên bản mới nhất: Thêm
@latestvào cấu hình của bạn:"args": ["-y", "@circleci/mcp-server-circleci@latest"] -
Khởi động lại IDE hoàn toàn (không chỉ tải lại cửa sổ)
Sự cố xác thực
- Lỗi token không hợp lệ: Xác minh
CIRCLECI_TOKENcủa bạn trong Personal API Tokens - Lỗi quyền: Đảm bảo token có quyền đọc cho các dự án của bạn
- Biến môi trường không tải: Kiểm tra với
echo $CIRCLECI_TOKEN(Mac/Linux) hoặcecho %CIRCLECI_TOKEN%(Windows)
Sự cố kết nối và mạng
- Base URL: Xác nhận
CIRCLECI_BASE_URLlàhttps://circleci.com - Mạng công ty: Cấu hình cài đặt proxy npm nếu ở sau tường lửa
- Tường lửa chặn: Kiểm tra xem phần mềm bảo mật có chặn tải xuống gói không
Yêu cầu hệ thống
- Phiên bản Node.js: Đảm bảo >= 18.0.0 với
node --version - Cập nhật Node.js: Cân nhắc LTS mới nhất nếu gặp sự cố tương thích
- Trình quản lý gói: Xác minh npm/pnpm hoạt động:
npm --version
Sự cố cụ thể theo IDE
- Vị trí tệp cấu hình: Kiểm tra lại đường dẫn cho hệ điều hành của bạn
- Lỗi cú pháp: Xác thực cú pháp JSON trong tệp cấu hình của bạn
- Nhật ký bảng điều khiển: Kiểm tra bảng điều khiển nhà phát triển IDE để tìm lỗi cụ thể
- Thử IDE khác: Kiểm tra trong một trình soạn thảo được hỗ trợ khác để cô lập sự cố
Sự cố quy trình
Quy trình treo — giết các quy trình MCP hiện có:
# Mac/Linux:
pkill -f "mcp-server-circleci"
# Windows:
taskkill /f /im node.exe
Xung đột cổng: Khởi động lại IDE nếu kết nối có vẻ bị chặn.
Gỡ lỗi nâng cao
- Kiểm tra gói trực tiếp:
npx @circleci/mcp-server-circleci@latest --help - Ghi nhật ký chi tiết:
DEBUG=* npx @circleci/mcp-server-circleci@latest - Dự phòng Docker: Thử cài đặt Docker nếu npx thất bại liên tục
Vẫn cần trợ giúp?
- Kiểm tra GitHub Issues để tìm các vấn đề tương tự
- Bao gồm hệ điều hành, phiên bản Node và IDE của bạn khi báo cáo sự cố
- Chia sẻ thông báo lỗi liên quan từ bảng điều khiển IDE
Telemetry
Máy chủ hỗ trợ số liệu OpenTelemetry để theo dõi việc sử dụng công cụ. Số liệu được xuất trừ khi bạn đặt DISABLE_TELEMETRY=true. Trên các triển khai từ xa, số liệu sử dụng cùng token với yêu cầu (PAT mỗi người dùng hoặc PAT máy chủ dùng chung).
| Số liệu | Mô tả |
|---|---|
circleci.mcp.tool.invocations | Số lần gọi công cụ |
circleci.mcp.tool.duration_ms | Thời gian thực thi tính bằng ms |
circleci.mcp.tool.errors | Số lỗi |
Phát triển
Bắt đầu
-
Sao chép kho lưu trữ:
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci -
Cài đặt phụ thuộc:
pnpm install -
Xây dựng dự án:
pnpm build
Xây dựng Container Docker
Bạn có thể xây dựng container Docker cục bộ bằng cách sử dụng:
docker build -t circleci:mcp-server-circleci .
Điều này sẽ tạo một hình ảnh Docker được gắn thẻ là circleci:mcp-server-circleci mà bạn có thể sử dụng với bất kỳ máy khách MCP nào.
Chế độ stdio cục bộ (một nhà phát triển, token trên máy khách):
docker run --rm -i \
-e CIRCLECI_TOKEN=your-circleci-token \
-e CIRCLECI_BASE_URL=https://circleci.com \
circleci/mcp-server-circleci
Chế độ từ xa (máy chủ tập trung cho nhóm): xem Self-Managed Remote MCP Server.
Phát triển với MCP Inspector
Cách dễ nhất để lặp lại trên MCP Server là sử dụng trình kiểm tra MCP. Bạn có thể tìm hiểu thêm về trình kiểm tra MCP tại https://modelcontextprotocol.io/docs/tools/inspector
-
Khởi động máy chủ phát triển:
pnpm watch # Keep this running in one terminal -
Trong một thiết bị đầu cuối riêng, khởi chạy trình kiểm tra:
pnpm inspector -
Cấu hình môi trường:
- Thêm
CIRCLECI_TOKENcủa bạn vào phần Biến môi trường trong giao diện trình kiểm tra - Token cần quyền đọc cho các dự án CircleCI của bạn
- Tùy chọn đặt Base URL CircleCI của bạn (mặc định là
https://circleci.com)
- Thêm
Kiểm thử
-
Chạy bộ kiểm thử:
pnpm test -
Chạy kiểm thử ở chế độ theo dõi trong quá trình phát triển:
pnpm test:watch
Để biết hướng dẫn đóng góp chi tiết hơn, xem CONTRIBUTING.md