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 CircleCI — Yêu cầu xác thực .circleci/config.yml của bạn để kiểm tra lỗi cú pháp và ngữ nghĩa thông qua config_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_pipeline hoặc chạy lại một workflow từ đầu hoặc từ job thất bại qua rerun_workflow.
  • Điều tra lỗi build — Truy xuất nhật ký lỗi chi tiết bằng get_build_failure_logs và kết quả kiểm thử qua get_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_data và tìm các lớp tài nguyên ít được sử dụng qua find_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-circleci khô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

License: Apache 2.0 CircleCI npm

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_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 xuống dữ liệu sử dụng từ CircleCI Usage API
find_flaky_testsXá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_classesTì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_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 công việc 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 công việc CircleCI
list_component_versionsLiệt kê tất cả các phiên bản cho 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ừ công việc thất bại
run_pipelineKích hoạt một pipeline để chạy
run_rollback_pipelineKí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:

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ỉ bắt buộc đối với khách hàng on-prem. MAX_MCP_OUTPUT_LENGTH là 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:

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:

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:

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:

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:

  1. Truy cập giao diện cấu hình MCP
  2. Chọn ký hiệu +
  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 truyền tải: stdio
  6. Nhập đường dẫn lệnh đến script của bạn
  7. 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ụngThiết lập máy chủThiết lập máy kháchNhậ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ợ SSOREQUIRE_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 đượcCIRCLECI_TOKEN trên máy chủ, REQUIRE_REQUEST_TOKEN=false (từ chối rõ ràng)Không cần header xác thựcMộ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í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 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ằng MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true. Kiểm tra Host/Origin khô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ế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 dùng chung)
CIRCLECI_TOKENPAT 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_URLTùy chọn — chỉ bắt buộc đối 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 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_ORIGINSDanh 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_HOSTGiao 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_ACCESSBắ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_ROOTSDanh 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_modules và 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 đó — /workspace trong container, /srv, /opt, một ổ đĩa 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. Đố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 Host trê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 đặt MCP_ALLOWED_HOSTS thành tên máy chủ mà máy khách sử dụng, nếu không mọi yêu cầu /mcp sẽ nhận được 403 Forbidden. Điểm cuối kiểm tra sức khỏe /ping khô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-remote không bao giờ gửi Origin, 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ỏ qua Origin để 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ủ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ẽ 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 Host thành địa chỉ backend (mặc định của nginx), hãy thêm proxy_set_header Host $host; để chuyển tên máy chủ gốc qua, sau đó đặt MCP_ALLOWED_HOSTS thành tên máy chủ công khai đó. Ngoài ra, bạn có thể đặt MCP_ALLOWED_HOSTS thà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/mcp vớ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ụng https://your-host/mcp mà 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.38 thay vì mcp-remote). Không sử 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 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 --headerAUTH_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.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ụ: "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:

  1. 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"
  2. Sử dụng URL dự án CircleCI:

  3. 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:

  1. 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"
  2. Sử dụng URL CircleCI:

  3. 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:

  1. 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"
  2. 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
  3. 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:
  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 dự án của tôi trên nhánh main"
  2. Sử dụng URL dự án CircleCI:

  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 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:

  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ê artifact cho dự án của tôi trên nhánh main"
  2. 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
  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 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 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 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:

  1. 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"
  2. Sử dụng URL CircleCI:

  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 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:

  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 có sẵn (tự động chọn nếu chỉ có một)
  3. 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)
  4. 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
  5. 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
  6. 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ó
  7. 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:

  1. Xóa bộ nhớ cache gói:

    npx clear-npx-cache
    npm cache clean --force
    
  2. Buộc 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ổ)

Sự cố 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 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ặc echo %CIRCLECI_TOKEN% (Windows)
Sự cố kết nối và mạng
  • Base URL: Xác nhận CIRCLECI_BASE_URLhttps://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?

  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 sự cố
  3. 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ệuMô 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 phụ thuộc:

    pnpm install
    
  3. 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

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

    pnpm watch # Keep this running in one terminal
    
  2. Trong một thiết bị đầu cuối riêng, khởi chạy trình kiểm tra:

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

    • Thêm CIRCLECI_TOKEN củ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)

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