CircleCI

chính thức

Cho 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 — Yêu cầu trợ lý xác thực .circleci/config.yml của bạn và nhận hướng dẫn về lỗi cú pháp và ngữ nghĩa thông qua config_helper.
  • Chẩn đoán lỗi build — Truy xuất nhật ký lỗi chi tiết từ một build CircleCI với get_build_failure_logs.
  • Tìm các 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 của một dự án với find_flaky_tests.
  • Kiểm tra trạng thái pipeline — Lấy trạng thái của pipeline mới nhất cho một nhánh bằng get_latest_pipeline_status.
  • Chạy lại workflow — Chạy lại một workflow từ đầu hoặc từ job bị lỗi với rerun_workflow.
  • Kích hoạt pipeline — Chạy một pipeline hoặc kích hoạt rollback dự án bằng run_pipeline và run_rollback_pipeline.

Tài liệu

[!IMPORTANT] Gói này đã bị ngừng hỗ trợ. Vui lòng chuyển sang giải pháp khác.

@circleci/mcp-server-circleci không còn được phát triển tính năng mới. Hãy sử dụng máy chủ MCP đượ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ữ (archive). Các phiên bản hiện có vẫn có thể cài đặt từ npm, nhưng không nên chạy một máy chủ không được bảo trì có chứa CircleCI Personal API Token.

Nếu bạn đang chạy giao vận từ xa tự quản lý (start=remote), hãy chuyển đổi trước: máy chủ được lưu trữ là giải pháp thay thế trực tiếp và loại bỏ nhu cầu vận hành một dịch vụ hướng ra mạng lưới làm trung gian cho token của tổ chức bạn.

CircleCI MCP Server

License: Apache 2.0 CircleCI npm

Model Context Protocol (MCP) là một giao thức chuẩn hóa mới để 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ỳ ứng dụng 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_helperXác thực và nhận hướng dẫn cho cấu hình CircleCI của bạn
download_usage_api_dataTải dữ liệu sử dụng từ CircleCI Usage API
find_flaky_testsXác định các bài kiểm thử không ổn định bằng cách phân tích lịch sử thực thi kiểm thử
find_underused_resource_classesTìm các job sử dụng tài nguyên tính toán chưa hiệu quả
get_build_failure_logsTruy xuất nhật ký lỗi chi tiết từ các bản dựng CircleCI
get_job_test_resultsTruy xuất siêu dữ liệu và kết quả kiểm thử cho các job CircleCI
get_latest_pipeline_statusLấy trạng thái của pipeline mới nhất cho một nhánh
list_artifactsLiệt kê các artifact được tạo bởi một job CircleCI
list_component_versionsLiệt kê tất cả các phiên bản của một thành phần CircleCI
list_followed_projectsLiệt kê tất cả các dự án CircleCI bạn đang theo dõi
rerun_workflowChạy lại một workflow từ đầu hoặc từ job bị lỗi
run_pipelineKích hoạt một pipeline để chạy
run_rollback_pipelineKích hoạt hoàn tác (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, xem Máy chủ MCP từ xa tự quản lý.

Cursor

Điều kiện tiên quyết:

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_URL là tùy chọn — chỉ cần thiết cho khách hàng on-prem. MAX_MCP_OUTPUT_LENGTH là tùy chọn — độ dài đầu ra tối đa cho các 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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý. Sử dụng cấu hình ứng dụng 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:

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 thông tin đầu vào sẽ đượ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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý. Sử dụng cấu hình ứng dụng khách theo từng người dùng trong .vscode/mcp.json.

Claude Desktop

Điều kiện tiên quyết:

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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý. Tạo một script wrapper như được trình bày trong Ứng dụng khách Claude Desktop và CLI, sau đó trỏ claude_desktop_config.json của bạn vào đó.

Để tìm hoặc tạo tệp cấu hình của bạn, mở cài đặt Claude Desktop, nhấp vào Developer ở 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:

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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý và phần thiết lập ứng dụng khách Claude Code tại đó.

Windsurf

Điều kiện tiên quyết:

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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý. Sử dụng cấu hình ứng dụng 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 ứng dụng khách MCP trong Amazon Q Developer được lưu ở đị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 — riêng cho workspace hiện tại

Nếu cả hai tệp đều 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 sẽ đượ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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý. Sử dụng một script wrapper như được trình bày trong Ứng dụng khách Claude Desktop và 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 Máy chủ MCP từ xa tự quản lý

Xem Máy chủ MCP từ xa tự quản lý. Sử dụng một script wrapper như được trình bày trong Ứng dụng khách Claude Desktop và CLI, sau đó thêm nó thông qua giao diện cấu hình MCP:

  1. Truy cập giao diện cấu hình MCP
  2. Chọn biểu tượng +
  3. Chọn phạm vi: global hoặc local
  4. Nhập tên (ví dụ: circleci-remote-mcp)
  5. Chọn giao thức vận chuyển: stdio
  6. Nhập đường dẫn lệnh đến script của bạn
  7. Nhấp vào 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

Máy chủ MCP từ xa tự quản lý

Chạy máy chủ MCP một cách 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ụngThiết lập máy chủThiết lập ứng dụng kháchNhật ký kiểm toán CircleCI
Token theo từng người dùng (khuyến nghị)Các nhóm có Personal API Token được hỗ trợ SSOREQUIRE_REQUEST_TOKEN=true, không có PAT trên 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, chấp nhận danh tính dịch vụ đơnCIRCLECI_TOKEN trên máy chủ, REQUIRE_REQUEST_TOKEN=false (từ chối rõ ràng)Không cần header xác thựcDanh 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 ở chế độ từ xa. Chế độ token dùng chung sẽ vô hiệu hóa nó (REQUIRE_REQUEST_TOKEN=false), khiến mọi người gọi đều có thể hành động với danh tính CIRCLECI_TOKEN củ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 nó trên mạng mà bạn hoàn toàn tin tưởng, và nếu không thì nên ưu tiên token theo từng người dùng. Việc kết thúc TLS tại 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ỉ liên kết không phải loopback, trừ khi bạn chấp nhận rủi ro một cách rõ ràng với MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true. Kiểm tra Host/Origin không thay thế cho xác thực — xem Bảo vệ chống tái liên kết DNS bên dưới.

1. Triển khai máy chủ

Cả hai chế độ đều sử dụng chế độ HTTP từ xa (start=remote). Công bố 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 tên máy chủ 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 tên máy chủ 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 công bố 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

Thay vào đó, nê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ếnMô tả
start=remoteKhởi động máy chủ MCP HTTP+SSE thay vì stdio
portCổng lắng nghe bên trong container (mặc định: 8000)
REQUIRE_REQUEST_TOKENTừ 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 chia sẻ)
CIRCLECI_TOKENPAT dự phòng dùng chung cho tất cả các yêu cầu khi không gửi header riêng cho từng người dùng
CIRCLECI_BASE_URLTùy chọn — chỉ bắt buộc với on-prem (mặc định: https://circleci.com)
DISABLE_TELEMETRY=trueTừ chối xuất số liệu sử dụng
MCP_ALLOWED_HOSTSDanh sách phân tách bằng dấu phẩy gồm các giá trị header Host bổ sung được phép (ví dụ: my-mcp.example.com,my-mcp.example.com:443). Các hostname loopback luôn được phép. Bắt buộc với mọi triển khai không phải loopback.
MCP_ALLOWED_ORIGINSDanh sách phân tách bằng dấu phẩy gồm các giá trị header Origin bổ sung được phép (ví dụ: https://my-app.example.com). Các origin loopback luôn được phép. Chỉ cần thiết khi trình duyệt truy cập trực tiếp máy chủ này (không qua mcp-remote).
MCP_BIND_HOSTGiao diện mạng để liên kết (mặc định: 0.0.0.0). Đặt thành 127.0.0.1 để chỉ giới hạn ở loopback (không tương thích với ánh xạ cổng -p của Docker).
MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESSBắt buộc (=true) để khởi động với REQUIRE_REQUEST_TOKEN=false trên địa chỉ liên kết không phải loopback. Xác nhận rằng bất kỳ peer nào có thể truy cập cổng đều hoạt động với 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 yêu cầu token cho yêu cầu.
MCP_FILE_OUTPUT_ROOTSDanh sách phân tách bằng dấu phẩy gồm 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 tạm luôn được phép. Xem ghi chú bên dưới.

Vị trí đầu ra tệp (áp dụng cho cả transport stdio và từ xa): 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ó thể đọ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 tạm của 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_modules và các thư mục launch-agent bị từ chối, cũng như các symlink trỏ ra 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. 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 đó — /workspace trong container, /srv, /opt, một volume phụ như /Volumes/work — hãy đặt MCP_FILE_OUTPUT_ROOTS thành thư mục đó, nếu không các đường dẫn đó sẽ bị từ chố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 với transport từ xa, nơi các đường dẫn đến từ máy khách mạng chứ không phải người dùng cục bộ.

Bảo vệ chống DNS-rebinding (không phải xác thực): Transport từ xa xác thực header Host trên mọi yêu cầu /mcp. Theo mặc định chỉ các địa chỉ loopback (localhost, 127.0.0.1, [::1]) được chấp nhận. Các triển khai công khai phải đặt MCP_ALLOWED_HOSTS thành hostname mà máy khách sử dụng, nếu không mọi yêu cầu /mcp sẽ nhận 403 Forbidden. Endpoint kiểm tra sức khỏe /ping không được bảo vệ để các probe của load-balancer 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-remote không bao giờ gửi Origin, nên 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 bên gọi chọn, nên bất kỳ máy khách không phải trình duyệt nào — curl, một script, một socket thô — đều có thể gửi Host được phép và bỏ qua Origin để thỏa mãn nó. Mục đích duy nhất của nó là ngăn một trình duyệt bị nhắm vào máy chủ bởi DNS do kẻ tấn công kiểm soát, đó chính là mối đe dọa DNS-rebinding. Xác thực bên gọi là nhiệm vụ của REQUIRE_REQUEST_TOKEN (hoặc một proxy xác thực phía trước cổng). Yêu cầu header Origin sẽ làm hỏng mọi máy khách CLI hợp lệ mà không ngăn được kẻ tấn công nào.

Phía sau reverse proxy: Nếu proxy của bạn ghi lại Host thành địa chỉ backend (mặc định của nginx), hãy thêm proxy_set_header Host $host; để chuyển tiếp hostname gốc, sau đó đặt MCP_ALLOWED_HOSTS thành hostname công khai đó. Hoặc, đặt MCP_ALLOWED_HOSTS thành bất kỳ hostname 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 trong header, nó sẽ được ưu tiên hơn CIRCLECI_TOKEN trên máy chủ.

Các số liệu telemetry được ghi trong một yêu cầu đượ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ợ 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: Dùng http://localhost:8000/mcp với --allow-http để kiểm thử cục bộ. Trong môi trường production, hãy kết thúc TLS tại ingress/load balancer của bạn và dùng https://your-host/mcp không có --allow-http.

Windows: Tránh khoảng trắng quanh dấu hai chấm trong các 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ụ dùng npx cho tiện. Với production hoặc triển khai cho 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.38 thay vì mcp-remote). Không dùng các phiên bản dưới 0.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 Personal API Token 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 chia sẻ

Khi máy chủ đã đặt CIRCLECI_TOKEN và được khởi động với REQUIRE_REQUEST_TOKEN=false (xác thực yêu cầu mặc định được bật và phải được tắt rõ ràng, và liên kết không phải loopback còn yêu cầu thêm 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"
      ]
    }
  }
}

Máy khách Claude Desktop và CLI

Tạo một script wrapper (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}"

Cấp quyền 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 dùng máy chủ token chia sẻ.

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

Bản 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.yml củ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ụ: "March 2025" hoặc "last month"). Tính năng chỉ dành cho Cloud.

Tùy chọn 1: Bắt đầu một tác vụ 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 tác vụ xuất hiện có bằng cách cung cấp:

  • orgId, jobId, outputDir

Trả về một tệp CSV chứa dữ liệu sử dụng CircleCI cho khung thời gian được 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 thử không ổn định trong dự án CircleCI của bạn bằng cách phân tích lịch sử thực thi kiểm thử. Tận dụng tính năng phát hiện kiểm thử không ổn định trong CircleCI.

Công cụ này có thể được dùng theo ba cách:

  1. Dùng Project Slug (Khuyến nghị):

    • Trước 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 thử không ổn định cho my-project"
  2. Dùng URL dự án CircleCI:

  3. 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 và URL git remote
    • Ví dụ: "Tìm các bài kiểm thử 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 kiểm thử 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 kiểm thử 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 job có mức sử dụng CPU/RAM trung bình hoặc tối đa dưới ngưỡng cho trước (mặc định: 40%).

Cung cấp một tệp CSV lấy từ download_usage_api_data.

Trả về danh sách markdown các job ít được sử dụng, được tổ chức theo dự án và workflow — hữu ích để xác định cơ hội tối ưu hóa chi phí.

get_build_failure_logs

Truy xuất log thất bại chi tiết từ các bản build CircleCI. Công cụ này có thể được dùng theo ba cách:

  1. Dùng Project Slug và Nhánh (Khuyến nghị):

    • Trước tiên dùng list_followed_projects để lấy các dự án của bạn, sau đó:
    • Ví dụ: "Lấy lỗi build cho my-project trên nhánh main"
  2. Dùng URL CircleCI:

  3. 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ụ: "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 đã định dạng bao gồm:

  • Tên job
  • Chi tiết thực thi từng bước
  • Thông báo lỗi và ngữ cảnh
get_job_test_results

Truy xuất siêu dữ liệu kiểm thử cho các job CircleCI, cho phép bạn phân tích kết quả kiểm thử mà không cần rời khỏi IDE. Công cụ này có thể được dùng theo ba cách:

  1. Dùng Project Slug và Nhánh (Khuyến nghị):

    • Ví dụ: "Lấy kết quả kiểm thử cho my-project trên nhánh main"
  2. Dùng URL CircleCI:

    • URL job: 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
  3. 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ề:

  • Tóm tắt tất cả các bài kiểm thử (tổng số, thành công, thất bại)
  • Thông tin chi tiết về các bài kiểm thử 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 thử thành công kèm thời gian
  • Lọc theo kết quả kiểm thử

[!NOTE] Siêu dữ liệu kiểm thử phải được cấu hình trong cấu hình CircleCI của bạn. Xem Thu thập dữ liệu kiểm thử để 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 nhất định. Công cụ này có thể được sử dụng theo ba cách:
  1. 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 my-project trên nhánh main"
  2. Sử dụng CircleCI Project URL:

  3. 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 workspace root, git remote URL 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 job CircleCI. Công cụ này có thể được sử dụng theo ba cách:

  1. 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ê các artifact cho my-project trên nhánh main"
  2. Sử dụng CircleCI URL:

    • Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
    • Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
    • Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
  3. 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 workspace root, git remote URL và tên nhánh

Hữu ích cho:

  • Tìm URL tải xuống cho các artifact build (binary, báo cáo, log)
  • 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 component 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 component và môi trường nếu chưa đượ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 rollback
  • Lấy 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 projectSlug củ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 đối với 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ừ job bị lỗi.

Trả về ID của workflow mới được tạo và một 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:

  1. Sử dụng Project Slug và Branch (Khuyến nghị):

    • Ví dụ: "Chạy pipeline cho my-project trên nhánh main"
  2. Sử dụng CircleCI URL:

  3. 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 workspace root, git remote URL và tên nhánh

Công cụ trả về một liên kết để theo dõi quá trình thực thi pipeline.

run_rollback_pipeline

Kích hoạt rollback cho một dự án CircleCI. Công cụ hướng dẫn bạn tương tác qua các bước:

  1. Chọn Dự án — liệt kê các dự án đang theo dõi để bạn chọn
  2. Chọn Môi trường — liệt kê các môi trường khả dụng (tự động chọn nếu chỉ có một)
  3. Chọn Component — liệt kê các component khả dụng (tự động chọn nếu chỉ có một)
  4. Chọn Phiên bản — hiển thị các phiên bản khả dụng; bạn chọn mục tiêu để rollback
  5. Phát hiện Chế độ Rollback — kiểm tra xem có pipeline rollback được cấu hình hay không
  6. Thực thi Rollback — hai tùy chọn:
    • Pipeline Rollback: kích hoạt pipeline rollback
    • Workflow Rerun: chạy lại một workflow trước đó bằng workflow ID của nó
  7. Xác nhận — tóm tắt và xác nhận trước khi thực thi

Khắc phục sự cố

Các bản sửa nhanh

Các vấn đề phổ biến nhất:

  1. Xóa bộ nhớ đệm gói:

    npx clear-npx-cache
    npm cache clean --force
    
  2. Buộc dùng phiên bản mới nhất: Thêm @latest vào cấu hình của bạn:

    "args": ["-y", "@circleci/mcp-server-circleci@latest"]
    
  3. Khởi động lại IDE hoàn toàn (không chỉ tải lại cửa sổ)

Vấn đề Xác thực
  • Lỗi token không hợp lệ: Xác minh CIRCLECI_TOKEN của bạn trong Personal API Tokens
  • Lỗi quyền: Đảm bảo token có quyền đọc đối với các dự án của bạn
  • Biến môi trường không được tải: Kiểm tra với echo $CIRCLECI_TOKEN (Mac/Linux) hoặc echo %CIRCLECI_TOKEN% (Windows)
Vấn đề Kết nối và Mạng
  • Base URL: Xác nhận CIRCLECI_BASE_URL là https://circleci.com
  • Mạng doanh nghiệp: Cấu hình cài đặt proxy npm nếu đằng 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 hay không
Yêu cầu Hệ thống
  • Phiên bản Node.js: Đảm bảo nó đáp ứng ^22.23.4 || ^24.22.1 || >=26.12.1 với node --version
  • Cập nhật Node.js: Cân nhắc dùng LTS mới nhất nếu gặp vấn đề tương thích
  • Trình quản lý gói: Xác minh npm/pnpm đang hoạt động: npm --version
Vấn đề Riêng 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ý console: Kiểm tra console nhà phát triển của 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 vấn đề
Vấn đề Tiến trình

Tiến trình bị treo — kết thúc các tiến 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 log chi tiết: DEBUG=* npx @circleci/mcp-server-circleci@latest
  • Dự phòng Docker: Thử cài đặt bằng Docker nếu npx liên tục thất bại

Vẫn cần trợ giúp?

  1. Kiểm tra GitHub Issues để tìm các vấn đề tương tự
  2. Bao gồm hệ điều hành, phiên bản Node và IDE của bạn khi báo cáo vấn đề
  3. Chia sẻ các thông báo lỗi liên quan từ console của IDE

Telemetry

Máy chủ hỗ trợ các chỉ số OpenTelemetry để theo dõi việc sử dụng công cụ. Các chỉ số được xuất trừ khi bạn đặt DISABLE_TELEMETRY=true. Trên các triển khai từ xa, các chỉ số sử dụng cùng token như yêu cầu (PAT của từng người dùng hoặc PAT máy chủ dùng chung).

Chỉ sốMô tả
circleci.mcp.tool.invocationsSố lần gọi công cụ
circleci.mcp.tool.duration_msThời gian thực thi tính bằng ms
circleci.mcp.tool.errorsSố lỗi

Phát triển

Bắt đầu

  1. Sao chép kho lưu trữ:

    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
    cd mcp-server-circleci
    
  2. Cài đặt các phụ thuộc:

    pnpm install
    
  3. Build dự án:

    pnpm build
    

Build Docker Container

Bạn có thể build Docker container cục bộ bằng cách sử dụng:

docker build -t circleci:mcp-server-circleci .

Lệnh này sẽ tạo một Docker image được gắn thẻ là circleci:mcp-server-circleci mà bạn có thể sử dụng với bất kỳ MCP client nào.

Chế độ stdio cục bộ (một nhà phát triển, token trên client):

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 một 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 việc phát triển MCP Server là sử dụng MCP inspector. Bạn có thể tìm hiểu thêm về MCP inspector tại https://modelcontextprotocol.io/docs/tools/inspector

  1. Khởi động máy chủ phát triển:

    pnpm watch # Keep this running in one terminal
    
  2. Trong một terminal riêng, khởi chạy inspector:

    pnpm inspector
    
  3. Cấu hình môi trường:

    • Thêm CIRCLECI_TOKEN của bạn vào phần Environment Variables trong giao diện inspector
    • Token cần có quyền đọc đối với các dự án CircleCI của bạn
    • Tùy chọn đặt CircleCI Base URL của bạn (mặc định là https://circleci.com)

Kiểm thử

  • Chạy bộ kiểm thử:

    pnpm test
    
  • Chạy kiểm thử ở chế độ watch 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