CircleCI

resmi

Memungkinkan Agen AI untuk memperbaiki kegagalan build dari CircleCI.

GitHub
94

Apa yang bisa Anda lakukan dengan CircleCI MCP?

  • Validasi konfigurasi CircleCI — Minta untuk memvalidasi .circleci/config.yml Anda untuk kesalahan sintaks dan semantik melalui config_helper.
  • Dapatkan status pipeline — Periksa status pipeline terbaru untuk sebuah cabang dengan get_latest_pipeline_status.
  • Picu dan jalankan ulang pipeline — Mulai pipeline baru dengan run_pipeline atau jalankan ulang workflow dari awal atau dari job yang gagal melalui rerun_workflow.
  • Selidiki kegagalan build — Ambil log kegagalan terperinci dengan get_build_failure_logs dan hasil tes melalui get_job_test_results.
  • Temukan tes flaky — Identifikasi tes flaky dengan menganalisis riwayat eksekusi tes menggunakan find_flaky_tests.
  • Analisis penggunaan dan biaya — Unduh data penggunaan dengan download_usage_api_data dan temukan kelas sumber daya yang kurang digunakan melalui find_underused_resource_classes.

Dokumentasi

[!IMPORTANT] Paket ini sudah tidak digunakan lagi (deprecated). Harap migrasi.

@circleci/mcp-server-circleci tidak lagi menerima pengembangan fitur. Gunakan MCP server terkelola CircleCI atau CircleCI CLI MCP sebagai gantinya — lihat Ringkasan MCP CircleCI.

Repositori ini akan diarsipkan. Versi yang ada tetap dapat diinstal dari npm, tetapi menjalankan server yang tidak terpelihara yang menyimpan CircleCI Personal API Token tidak disarankan.

Jika Anda menjalankan transport jarak jauh yang dikelola sendiri (start=remote), migrasikan terlebih dahulu: server terkelola adalah pengganti langsungnya dan menghilangkan kebutuhan untuk mengoperasikan layanan yang menghadap jaringan yang memediasi token organisasi Anda.

CircleCI MCP Server

License: Apache 2.0 CircleCI npm

Model Context Protocol (MCP) adalah protokol baru yang terstandarisasi untuk mengelola konteks antara model bahasa besar (LLM) dan sistem eksternal. Dalam repositori ini, kami menyediakan MCP Server untuk CircleCI.

Gunakan Cursor, Windsurf, Copilot, Claude, atau klien yang kompatibel dengan MCP untuk berinteraksi dengan CircleCI menggunakan bahasa alami — tanpa meninggalkan IDE Anda.

Tools

ToolDeskripsi
config_helperValidasi dan dapatkan panduan untuk konfigurasi CircleCI Anda
download_usage_api_dataUnduh data penggunaan dari CircleCI Usage API
find_flaky_testsIdentifikasi tes yang flaky dengan menganalisis riwayat eksekusi tes
find_underused_resource_classesTemukan job dengan sumber daya komputasi yang kurang dimanfaatkan
get_build_failure_logsAmbil log kegagalan terperinci dari build CircleCI
get_job_test_resultsAmbil metadata dan hasil tes untuk job CircleCI
get_latest_pipeline_statusDapatkan status pipeline terbaru untuk sebuah branch
list_artifactsDaftarkan artefak yang dihasilkan oleh job CircleCI
list_component_versionsDaftarkan semua versi untuk komponen CircleCI
list_followed_projectsDaftarkan semua proyek CircleCI yang Anda ikuti
rerun_workflowJalankan ulang workflow dari awal atau dari job yang gagal
run_pipelinePicu pipeline untuk dijalankan
run_rollback_pipelinePicu rollback untuk sebuah proyek

Instalasi

Deployment tim / terpusat: Untuk menjalankan satu server jarak jauh bersama untuk organisasi Anda (Kubernetes, Docker, dll.) dengan token CircleCI per-pengembang atau bersama, lihat Self-Managed Remote MCP Server.

Cursor

Prasyarat:

Menggunakan NPX di MCP Server lokal

Tambahkan berikut ini ke konfigurasi MCP Cursor Anda:

{
  "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 bersifat opsional — hanya diperlukan untuk pelanggan on-prem. MAX_MCP_OUTPUT_LENGTH bersifat opsional — panjang output maksimum untuk respons MCP (default: 50000).

Menggunakan Docker di MCP Server lokal

Tambahkan berikut ini ke konfigurasi MCP Cursor Anda:

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server. Gunakan konfigurasi klien per-pengguna dan tambahkan ke konfigurasi MCP Cursor Anda (Cursor Settings → MCP).

VS Code

Prasyarat:

Menggunakan NPX di MCP Server lokal

Tambahkan berikut ini ke .vscode/mcp.json di proyek Anda:

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

💡 Input diminta saat server pertama kali dimulai, kemudian disimpan dengan aman oleh VS Code.

Menggunakan Docker di MCP Server lokal

Tambahkan berikut ini ke .vscode/mcp.json di proyek Anda:

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server. Gunakan konfigurasi klien per-pengguna di .vscode/mcp.json.

Claude Desktop

Prasyarat:

Menggunakan NPX di MCP Server lokal

Tambahkan berikut ini ke claude_desktop_config.json Anda:

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

Menggunakan Docker di MCP Server lokal

Tambahkan berikut ini ke claude_desktop_config.json Anda:

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server. Buat skrip wrapper seperti yang ditunjukkan di Claude Desktop dan klien CLI, lalu arahkan claude_desktop_config.json Anda ke skrip tersebut.

Untuk menemukan atau membuat file konfigurasi Anda, buka pengaturan Claude Desktop, klik Developer di sidebar kiri, lalu klik Edit Config. File konfigurasi terletak di:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Untuk informasi lebih lanjut: https://modelcontextprotocol.io/quickstart/user

Claude Code

Prasyarat:

Menggunakan NPX di MCP Server lokal

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

Menggunakan Docker di MCP Server lokal

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server dan pengaturan klien Claude Code di sana.

Windsurf

Prasyarat:

Menggunakan NPX di MCP Server lokal

Tambahkan berikut ini ke mcp_config.json Windsurf Anda:

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

Menggunakan Docker di MCP Server lokal

Tambahkan berikut ini ke mcp_config.json Windsurf Anda:

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server. Gunakan konfigurasi klien per-pengguna di mcp_config.json Windsurf Anda.

Untuk informasi lebih lanjut: https://docs.windsurf.com/windsurf/mcp

Amazon Q Developer CLI

Prasyarat:

Konfigurasi klien MCP di Amazon Q Developer disimpan dalam format JSON di file bernama mcp.json. Dua tingkat konfigurasi didukung:

  • Global: ~/.aws/amazonq/mcp.json — berlaku untuk semua workspace
  • Workspace: .amazonq/mcp.json — khusus untuk workspace saat ini

Jika kedua file ada, isinya akan digabungkan. Jika terjadi konflik, konfigurasi workspace yang diutamakan.

Menggunakan NPX di MCP Server lokal

Edit ~/.aws/amazonq/mcp.json atau buat .amazonq/mcp.json dengan konten berikut:

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server. Gunakan skrip wrapper seperti yang ditunjukkan di Claude Desktop dan klien CLI, lalu daftarkan dengan q mcp add.

Amazon Q Developer di IDE

Prasyarat:

Menggunakan NPX di MCP Server lokal

Edit ~/.aws/amazonq/mcp.json atau buat .amazonq/mcp.json dengan konten berikut:

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

Menggunakan Self-Managed Remote MCP Server

Lihat Self-Managed Remote MCP Server. Gunakan skrip wrapper seperti yang ditunjukkan di Claude Desktop dan klien CLI, lalu tambahkan melalui UI konfigurasi MCP:

  1. Akses UI konfigurasi MCP
  2. Pilih simbol +
  3. Pilih cakupan: global atau lokal
  4. Masukkan nama (misalnya circleci-remote-mcp)
  5. Pilih protokol transport: stdio
  6. Masukkan path perintah ke skrip Anda
  7. Klik Simpan
Smithery

Untuk menginstal CircleCI MCP Server untuk Claude Desktop secara otomatis melalui Smithery:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Self-Managed Remote MCP Server

Jalankan MCP server secara terpusat (misalnya di Kubernetes atau Docker) sehingga tim Anda berbagi satu deployment. Pilih cara developer melakukan autentikasi:

Pilih mode deployment

ModeKapan digunakanPengaturan serverPengaturan klienJejak audit CircleCI
Token per-pengguna (disarankan)Tim dengan Personal API Token berbasis SSOREQUIRE_REQUEST_TOKEN=true, tanpa PAT serverSetiap developer meneruskan PAT merekaPer developer
Token bersama (sementara)Peluncuran cepat, identitas layanan tunggal dapat diterimaCIRCLECI_TOKEN di server, REQUIRE_REQUEST_TOKEN=false (opt-out eksplisit)Tidak perlu header authIdentitas bersama tunggal

Keamanan: Autentikasi permintaan aktif secara default dalam mode jarak jauh. Mode token bersama menonaktifkannya (REQUIRE_REQUEST_TOKEN=false), sehingga setiap pemanggil dapat bertindak sebagai identitas CIRCLECI_TOKEN server tanpa kredensial — termasuk memicu pipeline dengan konfigurasi arbitrer. Hanya aktifkan di jaringan yang sepenuhnya Anda percayai, dan utamakan token per-pengguna jika tidak demikian. Menghentikan TLS di ingress memberikan enkripsi, bukan autentikasi.

Karena kombinasi tersebut tidak aman di antarmuka publik, server menolak untuk dimulai ketika REQUIRE_REQUEST_TOKEN=false dikombinasikan dengan alamat bind non-loopback, kecuali Anda secara eksplisit menerima risiko dengan MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true. Pemeriksaan Host/Origin bukan pengganti autentikasi — lihat Perlindungan DNS-rebinding di bawah.

1. Deploy server

Kedua mode menggunakan mode HTTP jarak jauh (start=remote). Publikasikan port 8000 (atau port pilihan Anda).

Token per-pengguna (disarankan) — diakses melalui mcp-remote dari localhost:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e REQUIRE_REQUEST_TOKEN=true \
  circleci/mcp-server-circleci

Token per-pengguna (disarankan) — diakses melalui mcp-remote dari hostname publik:

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 bersama (sementara) — diakses melalui mcp-remote dari hostname publik:

Karena mode ini melayani PAT organisasi kepada pemanggil mana pun tanpa kredensial, mode ini hanya boleh dijalankan di mana port yang dipublikasikan tidak dapat dijangkau dari jaringan yang tidak tepercaya, dan Anda harus mengakuinya secara eksplisit atau server akan menolak untuk dimulai:

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

Utamakan menempatkan autentikasi di depan port sebagai gantinya — ingress yang memerlukan SSO, mTLS, atau API key — atau beralih ke token per-pengguna di atas.

Variabel lingkungan:

VariabelDeskripsi
start=remoteMenjalankan server MCP HTTP+SSE, bukan stdio
portPort listening di dalam container (default: 8000)
REQUIRE_REQUEST_TOKENMenolak permintaan tanpa header Authorization: Bearer atau Circle-Token. Default-nya wajib; setel REQUIRE_REQUEST_TOKEN=false untuk mengizinkan permintaan tanpa autentikasi (mode token bersama)
CIRCLECI_TOKENPAT fallback bersama untuk semua permintaan saat header per-pengguna tidak dikirim
CIRCLECI_BASE_URLOpsional — wajib hanya untuk on-prem (default: https://circleci.com)
DISABLE_TELEMETRY=trueMenonaktifkan ekspor metrik penggunaan
MCP_ALLOWED_HOSTSDaftar nilai header Host tambahan yang dipisahkan koma untuk diizinkan (mis. my-mcp.example.com,my-mcp.example.com:443). Hostname loopback selalu diizinkan. Wajib untuk semua deployment non-loopback.
MCP_ALLOWED_ORIGINSDaftar nilai header Origin tambahan yang dipisahkan koma untuk diizinkan (mis. https://my-app.example.com). Origin loopback selalu diizinkan. Hanya diperlukan saat browser mengakses server ini secara langsung (bukan melalui mcp-remote).
MCP_BIND_HOSTAntarmuka jaringan yang akan di-bind (default: 0.0.0.0). Setel ke 127.0.0.1 untuk membatasi hanya ke loopback (tidak kompatibel dengan pemetaan port Docker -p).
MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESSWajib (=true) untuk memulai dengan REQUIRE_REQUEST_TOKEN=false pada alamat bind non-loopback. Mengonfirmasi bahwa peer mana pun yang dapat menjangkau port tersebut bertindak sebagai identitas CIRCLECI_TOKEN server tanpa kredensial. Tidak berpengaruh saat token permintaan diwajibkan.
MCP_FILE_OUTPUT_ROOTSDaftar direktori tambahan yang dipisahkan koma yang boleh digunakan oleh alat baca/tulis file (mis. /srv/reports,/data/exports). Direktori kerja, direktori home, dan direktori temp selalu diizinkan. Lihat catatan di bawah.

Lokasi output file (berlaku untuk transport stdio dan remote): Alat yang menerima jalur filesystem — get_build_failure_logs (outputDir), download_usage_api_data (outputDir), dan find_underused_resource_classes (csvFilePath) — hanya boleh membaca dan menulis di dalam direktori kerja server, direktori home pengguna, dan direktori temp sistem. Di dalam root tersebut, direktori konfigurasi tersembunyi (~/.ssh, ~/.aws, ~/.config, .git, …), node_modules, dan direktori launch-agent ditolak, begitu juga symlink yang mengarah ke luar root yang diizinkan. Direktori sistem (/etc, /usr, /bin, /System, /Library, %SystemRoot%, …) ditolak tanpa syarat dan tidak dapat diaktifkan kembali. File output tidak pernah ditulis melalui symlink.

Jika checkout Anda berada di luar root tersebut — /workspace di dalam container, /srv, /opt, volume sekunder seperti /Volumes/work — setel MCP_FILE_OUTPUT_ROOTS ke direktori tersebut, jika tidak, jalur tersebut akan ditolak. Untuk server stdio, direktori kerja biasanya sudah merupakan root proyek, jadi tidak diperlukan konfigurasi. Ini paling penting untuk transport remote, tempat jalur berasal dari klien jaringan, bukan pengguna lokal.

Perlindungan DNS-rebinding (bukan autentikasi): Transport remote memvalidasi header Host pada setiap permintaan /mcp. Secara default, hanya alamat loopback (localhost, 127.0.0.1, [::1]) yang diterima. Deployment publik wajib menyetel MCP_ALLOWED_HOSTS ke hostname yang digunakan klien, jika tidak, semua permintaan /mcp akan menerima 403 Forbidden. Endpoint health-check /ping tidak dijaga sehingga probe load-balancer tetap berfungsi apa pun nilai Host.

Header Origin (dikirim oleh browser) juga divalidasi jika ada. Klien non-browser seperti mcp-remote tidak pernah mengirim Origin, sehingga tidak terpengaruh oleh pemeriksaan ini.

Pemeriksaan ini bukan kontrol akses dan tidak boleh diandalkan sebagai kontrol akses. Kedua header dipilih oleh pemanggil, sehingga klien non-browser mana pun — curl, skrip, raw socket — dapat mengirim Host yang diizinkan dan mengabaikan Origin untuk memenuhinya. Satu-satunya tujuannya adalah menghentikan browser agar tidak diarahkan ke server oleh DNS yang dikendalikan penyerang, yaitu ancaman DNS-rebinding. Autentikasi pemanggil adalah tugas REQUIRE_REQUEST_TOKEN (atau proxy autentikasi di depan port). Mewajibkan header Origin akan merusak semua klien CLI yang sah tanpa menghentikan penyerang mana pun.

Di belakang reverse proxy: Jika proxy Anda menulis ulang Host ke alamat backend (default nginx), tambahkan proxy_set_header Host $host; untuk meneruskan hostname asli, lalu setel MCP_ALLOWED_HOSTS ke hostname publik tersebut. Alternatifnya, setel MCP_ALLOWED_HOSTS ke hostname apa pun yang diteruskan proxy.

Server menerima token per-permintaan melalui:

  • Authorization: Bearer <circleci-pat>
  • Circle-Token: <circleci-pat>

Jika klien mengirim token header, token tersebut lebih diutamakan daripada CIRCLECI_TOKEN di server.

Metrik telemetri yang dicatat selama permintaan diekspor menggunakan token yang sama dengan permintaan tersebut.

2. Konfigurasi klien

Sebagian besar klien MCP hanya mendukung proses lokal (stdio). Gunakan mcp-remote, jembatan stdio-ke-HTTP pihak ketiga, untuk menghubungkannya ke server remote Anda.

Skema URL: Gunakan http://localhost:8000/mcp dengan --allow-http untuk pengujian lokal. Di produksi, akhiri TLS di ingress/load balancer Anda dan gunakan https://your-host/mcp tanpa --allow-http.

Windows: Hindari spasi di sekitar titik dua pada nilai --header. Letakkan seluruh nilai Bearer <token> di variabel lingkungan.

Keamanan: Contoh menggunakan npx demi kemudahan. Untuk produksi atau peluncuran tim, sematkan versi tertentu di konfigurasi MCP Anda (misalnya mcp-remote@0.1.38 alih-alih mcp-remote). Jangan gunakan versi di bawah 0.1.16 (CVE-2025-6514).

Konfigurasi klien: token per-pengguna

Setiap pengembang meneruskan CircleCI Personal API Token mereka sendiri pada setiap permintaan:

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

Ganti http://localhost:8000/mcp dengan URL server tim Anda. Cursor dan VS Code mendukung prompt ${input:...}; klien lain dapat menyetel AUTH_HEADER secara langsung.

Konfigurasi klien: token bersama

Saat server memiliki CIRCLECI_TOKEN disetel dan dimulai dengan REQUIRE_REQUEST_TOKEN=false (autentikasi permintaan aktif secara default dan harus dinonaktifkan secara eksplisit, dan bind non-loopback juga memerlukan MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true), klien tidak perlu mengirim token:

{
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http"
      ]
    }
  }
}

Klien Claude Desktop dan CLI

Buat skrip wrapper (mis. 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}"

Buat dapat dieksekusi (chmod +x circleci-remote-mcp.sh), lalu rujuk dari konfigurasi MCP Anda:

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

Hilangkan --header dan AUTH_HEADER saat menggunakan server token bersama.

3. Verifikasi deployment

# 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

Lihat aksinya

Contoh: "Temukan pipeline gagal terbaru di branch saya dan ambil lognya" — lihat wiki untuk contoh lainnya.

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

Detail Alat

config_helper

Membantu tugas konfigurasi CircleCI dengan memberikan panduan dan validasi.

  • Memvalidasi .circleci/config.yml Anda untuk kesalahan sintaks dan semantik
  • Memberikan hasil validasi terperinci dan rekomendasi konfigurasi
  • Contoh: "Validasi konfigurasi CircleCI saya"
download_usage_api_data

Mengunduh data penggunaan dari CircleCI Usage API untuk organisasi tertentu. Menerima input tanggal yang fleksibel (mis., "Maret 2025" atau "bulan lalu"). Fitur khusus cloud.

Opsi 1: Mulai pekerjaan ekspor baru dengan menyediakan:

  • orgId, startDate, endDate (maks 32 hari), outputDir

Opsi 2: Periksa/unduh pekerjaan ekspor yang ada dengan menyediakan:

  • orgId, jobId, outputDir

Mengembalikan file CSV dengan data penggunaan CircleCI untuk rentang waktu yang ditentukan.

[!NOTE] Data penggunaan dapat dimasukkan ke alat find_underused_resource_classes untuk analisis optimasi biaya.

find_flaky_tests

Mengidentifikasi tes flaky di proyek CircleCI Anda dengan menganalisis riwayat eksekusi tes. Memanfaatkan fitur deteksi tes flaky di CircleCI.

Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug (Disarankan):

    • Pertama gunakan list_followed_projects untuk mendapatkan proyek Anda, lalu:
    • Contoh: "Dapatkan tes flaky untuk proyek saya"

  2. Menggunakan URL Proyek CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari workspace lokal Anda dengan menyediakan root workspace dan URL remote git
    • Contoh: "Temukan tes flaky di proyek saya saat ini"

Mode output:

  • Teks (default): Mengembalikan detail tes flaky dalam format teks
  • File (memerlukan env var FILE_OUTPUT_DIRECTORY): Membuat direktori dengan detail tes flaky
find_underused_resource_classes

Menganalisis file CSV data penggunaan CircleCI untuk menemukan pekerjaan dengan penggunaan CPU/RAM rata-rata atau maksimum di bawah ambang batas tertentu (default: 40%).

Berikan file CSV yang diperoleh dari download_usage_api_data.

Mengembalikan daftar markdown pekerjaan yang kurang digunakan yang dikelompokkan berdasarkan proyek dan workflow — berguna untuk mengidentifikasi peluang optimasi biaya.

get_build_failure_logs

Mengambil log kegagalan terperinci dari build CircleCI. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug dan Branch (Disarankan):

    • Pertama gunakan list_followed_projects untuk mendapatkan proyek Anda, lalu:
    • Contoh: "Dapatkan kegagalan build untuk proyek saya di branch utama"

  2. Menggunakan URL CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari workspace lokal Anda dengan menyediakan root workspace, URL remote git, dan nama branch
    • Contoh: "Temukan pipeline gagal terbaru di branch saya saat ini"

Alat mengembalikan log terformat termasuk:

  • Nama pekerjaan
  • Detail eksekusi langkah demi langkah
  • Pesan kegagalan dan konteks
get_job_test_results

Mengambil metadata tes untuk pekerjaan CircleCI, memungkinkan Anda menganalisis hasil tes tanpa meninggalkan IDE. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug dan Branch (Disarankan):

    • Contoh: "Dapatkan hasil tes untuk proyek saya di branch utama"

  2. Menggunakan URL CircleCI:

    • URL pekerjaan: 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. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari workspace lokal Anda dengan menyediakan root workspace, URL remote git, dan nama branch

Alat mengembalikan:

  • Ringkasan semua tes (total, berhasil, gagal)
  • Informasi terperinci tentang tes yang gagal: nama, kelas, file, pesan kesalahan, durasi
  • Daftar tes yang berhasil dengan waktu
  • Filter berdasarkan hasil tes

[!NOTE] Metadata tes harus dikonfigurasi di konfigurasi CircleCI Anda. Lihat Collect Test Data untuk petunjuk pengaturan.

get_latest_pipeline_status Mengambil status pipeline terbaru untuk cabang tertentu. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug dan Cabang (Disarankan):

    • Contoh: "Dapatkan status pipeline terbaru untuk my-project pada cabang main"

  2. Menggunakan URL Proyek CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari workspace lokal Anda dengan menyediakan root workspace, URL remote git, dan nama cabang

Contoh keluaran:

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

Mengambil daftar artefak yang dihasilkan oleh pekerjaan CircleCI. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug dan Cabang (Disarankan):

    • Pertama gunakan list_followed_projects untuk mendapatkan proyek Anda, lalu:
    • Contoh: "Daftarkan artefak untuk my-project pada cabang main"

  2. Menggunakan URL CircleCI:

    • URL Pekerjaan: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
    • URL Alur Kerja: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
    • URL Pipeline: https://app.circleci.com/pipelines/gh/organization/project/123

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari workspace lokal Anda dengan menyediakan root workspace, URL remote git, dan nama cabang

Berguna untuk:

  • Menemukan URL unduhan untuk artefak build (binari, laporan, log)
  • Memeriksa artefak apa yang dihasilkan oleh proses pipeline
list_component_versions

Mencantumkan semua versi untuk komponen CircleCI tertentu dalam suatu lingkungan. Termasuk status penerapan, informasi commit, dan stempel waktu.

Alat ini akan meminta Anda memilih komponen dan lingkungan jika tidak disediakan.

Berguna untuk:

  • Mengidentifikasi versi mana yang saat ini aktif
  • Memilih versi target untuk operasi rollback
  • Mendapatkan detail penerapan (pipeline, alur kerja, pekerjaan)
list_followed_projects

Mencantumkan semua proyek yang diikuti pengguna di CircleCI.

  • Menampilkan semua proyek yang Anda miliki aksesnya beserta projectSlug mereka
  • Contoh: "Daftarkan proyek CircleCI saya"

Contoh keluaran:

Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)

[!NOTE] projectSlug (bukan nama proyek) diperlukan untuk banyak alat CircleCI lainnya.

rerun_workflow

Menjalankan ulang alur kerja dari awal atau dari pekerjaan yang gagal.

Mengembalikan ID alur kerja yang baru dibuat dan tautan untuk memantaunya.

run_pipeline

Memicu pipeline untuk berjalan. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug dan Cabang (Disarankan):

    • Contoh: "Jalankan pipeline untuk my-project pada cabang main"

  2. Menggunakan URL CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari workspace lokal Anda dengan menyediakan root workspace, URL remote git, dan nama cabang

Alat ini mengembalikan tautan untuk memantau eksekusi pipeline.

run_rollback_pipeline

Memicu rollback untuk proyek CircleCI. Alat ini memandu Anda secara interaktif melalui:

  1. Pemilihan Proyek — mencantumkan proyek yang diikuti untuk Anda pilih
  2. Pemilihan Lingkungan — mencantumkan lingkungan yang tersedia (memilih otomatis jika hanya satu)
  3. Pemilihan Komponen — mencantumkan komponen yang tersedia (memilih otomatis jika hanya satu)
  4. Pemilihan Versi — menampilkan versi yang tersedia; Anda memilih target untuk rollback
  5. Deteksi Mode Rollback — memeriksa apakah pipeline rollback dikonfigurasi
  6. Jalankan Rollback — dua opsi:
    • Pipeline Rollback: memicu pipeline rollback
    • Jalankan Ulang Alur Kerja: menjalankan ulang alur kerja sebelumnya menggunakan ID alur kerjanya
  7. Konfirmasi — merangkum dan mengonfirmasi sebelum eksekusi

Pemecahan Masalah

Perbaikan Cepat

Masalah paling umum:

  1. Bersihkan cache paket:

    npx clear-npx-cache
npm cache clean --force

  2. Paksa versi terbaru: Tambahkan @latest ke konfigurasi Anda:

    "args": ["-y", "@circleci/mcp-server-circleci@latest"]

  3. Mulai ulang IDE Anda sepenuhnya (bukan hanya memuat ulang jendela)

Masalah Autentikasi
  • Kesalahan token tidak valid: Verifikasi CIRCLECI_TOKEN Anda di Token API Pribadi
  • Kesalahan izin: Pastikan token memiliki akses baca ke proyek Anda
  • Variabel lingkungan tidak dimuat: Uji dengan echo $CIRCLECI_TOKEN (Mac/Linux) atau echo %CIRCLECI_TOKEN% (Windows)
Masalah Koneksi dan Jaringan
  • URL Dasar: Konfirmasi CIRCLECI_BASE_URL adalah https://circleci.com
  • Jaringan perusahaan: Konfigurasikan pengaturan proxy npm jika berada di belakang firewall
  • Pemblokiran firewall: Periksa apakah perangkat lunak keamanan memblokir unduhan paket
Persyaratan Sistem
  • Versi Node.js: Pastikan >= 18.0.0 dengan node --version
  • Perbarui Node.js: Pertimbangkan LTS terbaru jika mengalami masalah kompatibilitas
  • Manajer paket: Verifikasi npm/pnpm berfungsi: npm --version
Masalah Khusus IDE
  • Lokasi file konfigurasi: Periksa kembali jalur untuk OS Anda
  • Kesalahan sintaks: Validasi sintaks JSON di file konfigurasi Anda
  • Log konsol: Periksa konsol pengembang IDE untuk kesalahan spesifik
  • Coba IDE lain: Uji di editor lain yang didukung untuk mengisolasi masalah
Masalah Proses

Proses yang menggantung — hentikan proses MCP yang ada:

# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

Konflik port: Mulai ulang IDE Anda jika koneksi tampak terblokir.

Debugging Lanjutan
  • Uji paket secara langsung: npx @circleci/mcp-server-circleci@latest --help
  • Pencatatan verbose: DEBUG=* npx @circleci/mcp-server-circleci@latest
  • Cadangan Docker: Coba instalasi Docker jika npx gagal secara konsisten

Masih butuh bantuan?

  1. Periksa Masalah GitHub untuk masalah serupa
  2. Sertakan OS, versi Node, dan IDE Anda saat melaporkan masalah
  3. Bagikan pesan kesalahan yang relevan dari konsol IDE

Telemetri

Server mendukung metrik OpenTelemetry untuk melacak penggunaan alat. Metrik diekspor kecuali Anda menetapkan DISABLE_TELEMETRY=true. Pada penerapan jarak jauh, metrik menggunakan token yang sama dengan permintaan (PAT per pengguna atau PAT server bersama).

MetrikDeskripsi
circleci.mcp.tool.invocationsJumlah pemanggilan alat
circleci.mcp.tool.duration_msWaktu eksekusi dalam ms
circleci.mcp.tool.errorsJumlah kesalahan

Pengembangan

Memulai

  1. Klon repositori:

    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci

  2. Instal dependensi:

    pnpm install

  3. Bangun proyek:

    pnpm build

Membangun Kontainer Docker

Anda dapat membangun kontainer Docker secara lokal menggunakan:

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

Ini akan membuat citra Docker yang diberi tag sebagai circleci:mcp-server-circleci yang dapat Anda gunakan dengan klien MCP mana pun.

Mode stdio lokal (pengembang tunggal, token di klien):

docker run --rm -i \
  -e CIRCLECI_TOKEN=your-circleci-token \
  -e CIRCLECI_BASE_URL=https://circleci.com \
  circleci/mcp-server-circleci

Mode jarak jauh (server terpusat untuk tim): lihat Server MCP Jarak Jauh yang Dikelola Sendiri.

Pengembangan dengan MCP Inspector

Cara termudah untuk mengulangi MCP Server adalah menggunakan inspektur MCP. Anda dapat mempelajari lebih lanjut tentang inspektur MCP di https://modelcontextprotocol.io/docs/tools/inspector

  1. Mulai server pengembangan:

    pnpm watch # Keep this running in one terminal

  2. Di terminal terpisah, luncurkan inspektur:

    pnpm inspector

  3. Konfigurasikan lingkungan:

    • Tambahkan CIRCLECI_TOKEN Anda ke bagian Variabel Lingkungan di UI inspektur
    • Token memerlukan akses baca ke proyek CircleCI Anda
    • Secara opsional atur URL Dasar CircleCI Anda (defaultnya ke https://circleci.com)

Pengujian

  • Jalankan rangkaian pengujian:

    pnpm test

  • Jalankan pengujian dalam mode pantau selama pengembangan:

    pnpm test:watch

Untuk pedoman kontribusi yang lebih rinci, lihat CONTRIBUTING.md