CircleCI

resmi

Memungkinkan Agen AI untuk memperbaiki kegagalan build dari CircleCI.

GitHub
94

Apa yang bisa Anda lakukan dengan CircleCI MCP?

  • Validasi konfigurasi — Minta asisten memvalidasi .circleci/config.yml Anda dan mendapatkan panduan tentang kesalahan sintaks dan semantik melalui config_helper.
  • Diagnosis kegagalan build — Ambil log kegagalan terperinci dari build CircleCI dengan get_build_failure_logs.
  • Temukan pengujian yang tidak stabil — Identifikasi pengujian yang tidak stabil dengan menganalisis riwayat eksekusi pengujian untuk suatu proyek menggunakan find_flaky_tests.
  • Periksa status pipeline — Dapatkan status pipeline terbaru untuk suatu branch menggunakan get_latest_pipeline_status.
  • Jalankan ulang workflow — Jalankan ulang workflow dari awal atau dari job yang gagal dengan rerun_workflow.
  • Picu pipeline — Jalankan pipeline atau picu rollback proyek menggunakan run_pipeline dan run_rollback_pipeline.

Dokumentasi

[!IMPORTANT] Paket ini sudah tidak digunakan lagi. Silakan bermigrasi.

@circleci/mcp-server-circleci tidak lagi menerima pengembangan fitur. Gunakan server MCP yang di-host atau MCP CLI CircleCI — lihat Ringkasan MCP CircleCI.

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

Jika Anda menjalankan transport jarak jauh yang dikelola sendiri (start=remote), lakukan migrasi terlebih dahulu: server yang di-host adalah pengganti langsungnya dan menghilangkan kebutuhan untuk mengoperasikan layanan yang terhubung ke jaringan dan menjadi perantara token org Anda.

Server MCP CircleCI

License: Apache 2.0 CircleCI npm

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

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

Alat

AlatDeskripsi
config_helperMemvalidasi dan memberikan panduan untuk konfigurasi CircleCI Anda
download_usage_api_dataMengunduh data penggunaan dari Usage API CircleCI
find_flaky_testsMengidentifikasi pengujian yang tidak stabil dengan menganalisis riwayat eksekusi pengujian
find_underused_resource_classesMenemukan job dengan sumber daya komputasi yang kurang dimanfaatkan
get_build_failure_logsMengambil log kegagalan terperinci dari build CircleCI
get_job_test_resultsMengambil metadata dan hasil pengujian untuk job CircleCI
get_latest_pipeline_statusMendapatkan status pipeline terbaru untuk sebuah branch
list_artifactsMencantumkan artefak yang dihasilkan oleh job CircleCI
list_component_versionsMencantumkan semua versi untuk komponen CircleCI
list_followed_projectsMencantumkan semua proyek CircleCI yang Anda ikuti
rerun_workflowMenjalankan ulang workflow dari awal atau dari job yang gagal
run_pipelineMemicu pipeline untuk dijalankan
run_rollback_pipelineMemicu rollback untuk sebuah proyek

Instalasi

Penerapan tim/terpusat: Untuk menjalankan satu server jarak jauh bersama bagi org Anda (Kubernetes, Docker, dll.) dengan token CircleCI per pengembang atau bersama, lihat Server MCP Jarak Jauh yang Dikelola Sendiri.

Cursor

Prasyarat:

Menggunakan NPX di Server MCP 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 Server MCP 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri. Gunakan konfigurasi klien per pengguna dan tambahkan ke konfigurasi MCP Cursor Anda (Cursor Settings → MCP).

VS Code

Prasyarat:

Menggunakan NPX di Server MCP 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 akan diminta saat server pertama kali dimulai, lalu disimpan dengan aman oleh VS Code.

Menggunakan Docker di Server MCP 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri. Gunakan konfigurasi klien per pengguna di .vscode/mcp.json.

Claude Desktop

Prasyarat:

Menggunakan NPX di Server MCP 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 Server MCP 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri. Buat skrip wrapper seperti yang ditunjukkan di Klien Claude Desktop dan CLI, lalu arahkan claude_desktop_config.json Anda ke skrip tersebut.

Untuk menemukan atau membuat file konfigurasi, buka pengaturan Claude Desktop, klik Developer di bilah sisi kiri, lalu klik Edit Config. File konfigurasi berada di:

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

Informasi selengkapnya: https://modelcontextprotocol.io/quickstart/user

Claude Code

Prasyarat:

Menggunakan NPX di Server MCP lokal

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

Menggunakan Docker di Server MCP 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri dan penyiapan klien Claude Code di sana.

Windsurf

Prasyarat:

Menggunakan NPX di Server MCP 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 Server MCP 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri. Gunakan konfigurasi klien per pengguna di mcp_config.json Windsurf Anda.

Informasi selengkapnya: 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 tersedia, isinya akan digabungkan. Jika terjadi konflik, konfigurasi workspace akan diutamakan.

Menggunakan NPX di Server MCP lokal

Edit ~/.aws/amazonq/mcp.json atau buat .amazonq/mcp.json dengan isi 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri. Gunakan skrip wrapper seperti yang ditunjukkan di Klien Claude Desktop dan CLI, lalu daftarkan dengan q mcp add.

Amazon Q Developer di IDE

Prasyarat:

Menggunakan NPX di Server MCP lokal

Edit ~/.aws/amazonq/mcp.json atau buat .amazonq/mcp.json dengan isi 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 Server MCP Jarak Jauh yang Dikelola Sendiri

Lihat Server MCP Jarak Jauh yang Dikelola Sendiri. Gunakan skrip wrapper seperti yang ditunjukkan di Klien Claude Desktop dan CLI, lalu tambahkan melalui UI konfigurasi MCP:

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

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

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

Server MCP Jarak Jauh yang Dikelola Sendiri

Jalankan server MCP secara terpusat (misalnya di Kubernetes atau Docker) agar tim Anda menggunakan satu penerapan bersama. Pilih cara pengembang melakukan autentikasi:

Pilih mode penerapan

ModeKapan digunakanPenyiapan serverPenyiapan klienJejak audit CircleCI
Token per pengguna (disarankan)Tim dengan Personal API Token yang didukung SSOREQUIRE_REQUEST_TOKEN=true, tanpa PAT serverSetiap pengembang meneruskan PAT merekaPer pengembang
Token bersama (sementara)Peluncuran cepat, satu identitas layanan dapat diterimaCIRCLECI_TOKEN di server, REQUIRE_REQUEST_TOKEN=false (pengecualian eksplisit)Tidak perlu header autentikasiSatu identitas bersama

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 sembarang. Aktifkan mode ini hanya di jaringan yang sepenuhnya Anda percayai, dan utamakan token per pengguna. Mengakhiri TLS di ingress menyediakan enkripsi, bukan autentikasi.

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

1. Terapkan 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 menyediakan PAT org kepada pemanggil mana pun tanpa kredensial, mode ini hanya boleh dijalankan di tempat port yang dipublikasikan tidak dapat dijangkau dari jaringan yang tidak tepercaya, dan Anda harus menyatakan persetujuan secara eksplisit; jika tidak, 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

Sebaiknya tempatkan autentikasi di depan port — misalnya ingress yang mewajibkan SSO, mTLS, atau kunci API — atau beralih ke token per pengguna di atas.

Variabel lingkungan:

VariabelDeskripsi
start=remoteMemulai server MCP HTTP+SSE, bukan stdio
portPort yang didengarkan di dalam container (default: 8000)
REQUIRE_REQUEST_TOKENMenolak permintaan tanpa header Authorization: Bearer atau Circle-Token. Wajib secara default; atur REQUIRE_REQUEST_TOKEN=false untuk mengizinkan permintaan tanpa autentikasi (mode token bersama)
CIRCLECI_TOKENPAT cadangan bersama untuk semua permintaan jika header per pengguna tidak dikirim
CIRCLECI_BASE_URLOpsional — hanya diperlukan untuk on-prem (default: https://circleci.com)
DISABLE_TELEMETRY=trueMenonaktifkan ekspor metrik penggunaan
MCP_ALLOWED_HOSTSDaftar nilai header Host tambahan yang dipisahkan koma dan diizinkan (misalnya my-mcp.example.com,my-mcp.example.com:443). Nama host loopback selalu diizinkan. Wajib untuk deployment non-loopback apa pun.
MCP_ALLOWED_ORIGINSDaftar nilai header Origin tambahan yang dipisahkan koma dan diizinkan (misalnya https://my-app.example.com). Origin loopback selalu diizinkan. Hanya diperlukan jika browser mengakses server ini secara langsung (bukan melalui mcp-remote).
MCP_BIND_HOSTAntarmuka jaringan yang akan diikat (default: 0.0.0.0). Atur 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. Menyatakan bahwa setiap peer yang dapat menjangkau port bertindak sebagai identitas CIRCLECI_TOKEN server tanpa kredensial. Tidak berpengaruh jika token permintaan diwajibkan.
MCP_FILE_OUTPUT_ROOTSDaftar direktori tambahan yang dipisahkan koma dan dapat digunakan oleh alat baca/tulis file (misalnya /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 sistem file — get_build_failure_logs (outputDir), download_usage_api_data (outputDir) dan find_underused_resource_classes (csvFilePath) — hanya dapat membaca dan menulis di dalam direktori kerja server, direktori home pengguna, dan direktori temp sistem. Di dalam direktori tersebut, direktori konfigurasi tersembunyi (~/.ssh, ~/.aws, ~/.config, .git, …), node_modules dan direktori launch-agent ditolak, begitu pula symlink yang mengarah ke luar direktori yang diizinkan. Direktori sistem (/etc, /usr, /bin, /System, /Library, %SystemRoot%, …) selalu ditolak dan tidak dapat diizinkan kembali. File output tidak pernah ditulis melalui symlink.

Jika checkout Anda berada di luar direktori tersebut — /workspace di dalam container, /srv, /opt, volume sekunder seperti /Volumes/work — atur MCP_FILE_OUTPUT_ROOTS ke direktori tersebut; jika tidak, jalur itu akan ditolak. Untuk server stdio, direktori kerja biasanya sudah merupakan root proyek, sehingga tidak diperlukan konfigurasi. Hal ini paling penting untuk transport remote, karena jalurnya 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 harus mengatur MCP_ALLOWED_HOSTS ke nama host yang digunakan klien, atau semua permintaan /mcp akan menerima 403 Forbidden. Endpoint pemeriksaan kesehatan /ping tidak dilindungi agar pemeriksaan load balancer tetap berfungsi terlepas dari Host.

Header Origin (yang 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 apa pun — curl, skrip, soket mentah — dapat mengirim Host yang diizinkan dan menghilangkan Origin untuk memenuhinya. Tujuannya hanya untuk mencegah browser diarahkan ke server oleh DNS yang dikendalikan penyerang, yaitu ancaman DNS rebinding. Autentikasi pemanggil ditangani oleh 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 balik reverse proxy: Jika proxy Anda menulis ulang Host ke alamat backend (default nginx), tambahkan proxy_set_header Host $host; untuk meneruskan nama host asli, lalu atur MCP_ALLOWED_HOSTS ke nama host publik tersebut. Sebagai alternatif, atur MCP_ALLOWED_HOSTS ke nama host apa pun yang diteruskan oleh 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. Konfigurasikan klien

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

Skema URL: Gunakan http://localhost:8000/mcp dengan --allow-http untuk pengujian lokal. Dalam 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. Masukkan seluruh nilai Bearer <token> ke dalam variabel lingkungan.

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

Konfigurasi klien: token per pengguna

Setiap developer meneruskan CircleCI Personal API Token miliknya 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 perintah ${input:...}; klien lain dapat mengatur AUTH_HEADER secara langsung.

Konfigurasi klien: token bersama

Jika server telah mengatur CIRCLECI_TOKEN dan dijalankan dengan REQUIRE_REQUEST_TOKEN=false (autentikasi permintaan aktif secara default dan harus dinonaktifkan secara eksplisit; 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"
      ]
    }
  }
}

Claude Desktop dan klien CLI

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

Jadikan skrip dapat dieksekusi (chmod +x circleci-remote-mcp.sh), lalu rujuk skrip tersebut 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 cara kerjanya

Contoh: "Temukan pipeline gagal terbaru di branch saya dan ambil log-nya" — 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 menemukan kesalahan sintaks dan semantik
  • Memberikan hasil validasi terperinci dan rekomendasi konfigurasi
  • Contoh: "Validasi konfigurasi CircleCI saya"
download_usage_api_data

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

Opsi 1: Mulai tugas ekspor baru dengan memberikan:

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

Opsi 2: Periksa/unduh tugas ekspor yang sudah ada dengan memberikan:

  • orgId, jobId, outputDir

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

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

find_flaky_tests

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

Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug (Disarankan):

    • Gunakan list_followed_projects terlebih dahulu untuk mendapatkan proyek Anda, lalu:
    • Contoh: "Dapatkan pengujian flaky untuk my-project"

  2. Menggunakan URL Proyek CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari ruang kerja lokal Anda dengan memberikan root ruang kerja dan URL remote git
    • Contoh: "Temukan pengujian flaky di proyek saya saat ini"

Mode output:

  • Teks (default): Mengembalikan detail pengujian flaky dalam format teks
  • File (memerlukan variabel env FILE_OUTPUT_DIRECTORY): Membuat direktori berisi detail pengujian flaky
find_underused_resource_classes

Menganalisis file CSV data penggunaan CircleCI untuk menemukan job 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 berisi job yang kurang dimanfaatkan, 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):

    • Gunakan list_followed_projects terlebih dahulu untuk mendapatkan proyek Anda, lalu:
    • Contoh: "Dapatkan kegagalan build untuk my-project di branch main"

  2. Menggunakan URL CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

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

Alat ini mengembalikan log berformat yang mencakup:

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

Mengambil metadata pengujian untuk job CircleCI, sehingga Anda dapat menganalisis hasil pengujian tanpa meninggalkan IDE. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Project Slug dan Branch (Disarankan):

    • Contoh: "Dapatkan hasil pengujian untuk my-project di branch main"

  2. Menggunakan 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. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari ruang kerja lokal Anda dengan memberikan root ruang kerja, URL remote git, dan nama branch

Alat ini mengembalikan:

  • Ringkasan semua pengujian (total, berhasil, gagal)
  • Info terperinci tentang pengujian yang gagal: nama, kelas, file, pesan kesalahan, durasi
  • Daftar pengujian yang berhasil beserta waktunya
  • Filter berdasarkan hasil pengujian

[!NOTE] Metadata pengujian harus dikonfigurasi di konfigurasi CircleCI Anda. Lihat Kumpulkan Data Pengujian untuk petunjuk penyiapan.

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

  1. Menggunakan Slug Proyek dan Branch (Disarankan):

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

  2. Menggunakan URL Proyek CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari ruang kerja lokal Anda dengan memberikan root ruang kerja, URL remote git, dan nama branch

Contoh output:

---
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 job CircleCI. Alat ini dapat digunakan dengan tiga cara:

  1. Menggunakan Slug Proyek dan Branch (Disarankan):

    • Gunakan list_followed_projects terlebih dahulu untuk mendapatkan proyek Anda, lalu:
    • Contoh: "Daftar artefak untuk my-project pada branch main"

  2. Menggunakan URL CircleCI:

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

    • Berfungsi dari ruang kerja lokal Anda dengan memberikan root ruang kerja, URL remote git, dan nama branch

Berguna untuk:

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

Mencantumkan semua versi komponen CircleCI tertentu di suatu lingkungan. Mencakup status deployment, informasi commit, dan stempel waktu.

Alat akan meminta Anda memilih komponen dan lingkungan jika belum diberikan.

Berguna untuk:

  • Mengetahui versi yang sedang aktif
  • Memilih versi target untuk operasi rollback
  • Mendapatkan detail deployment (pipeline, workflow, job)
list_followed_projects

Mencantumkan semua proyek yang diikuti pengguna di CircleCI.

  • Menampilkan semua proyek yang dapat Anda akses beserta projectSlug
  • Contoh: "Daftar proyek CircleCI saya"

Contoh output:

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

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

rerun_workflow

Menjalankan ulang workflow dari awal atau dari job yang gagal.

Mengembalikan ID workflow yang baru dibuat dan tautan untuk memantaunya.

run_pipeline

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

  1. Menggunakan Slug Proyek dan Branch (Disarankan):

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

  2. Menggunakan URL CircleCI:

  3. Menggunakan Konteks Proyek Lokal:

    • Berfungsi dari ruang kerja lokal Anda dengan memberikan root ruang kerja, URL remote git, dan nama branch

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 (dipilih otomatis jika hanya ada satu)
  3. Pemilihan Komponen — mencantumkan komponen yang tersedia (dipilih otomatis jika hanya ada satu)
  4. Pemilihan Versi — menampilkan versi yang tersedia; Anda memilih target rollback
  5. Deteksi Mode Rollback — memeriksa apakah pipeline rollback telah dikonfigurasi
  6. Eksekusi Rollback — dua opsi:
    • Rollback Pipeline: memicu pipeline rollback
    • Menjalankan Ulang Workflow: menjalankan ulang workflow sebelumnya menggunakan ID workflow-nya
  7. Konfirmasi — merangkum dan mengonfirmasi sebelum eksekusi

Pemecahan Masalah

Perbaikan Cepat

Masalah yang paling umum:

  1. Hapus cache paket:

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

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

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

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

Masalah Autentikasi
  • Kesalahan token tidak valid: Verifikasi CIRCLECI_TOKEN Anda di Personal API Tokens
  • 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: Pastikan CIRCLECI_BASE_URL adalah https://circleci.com
  • Jaringan perusahaan: Konfigurasikan pengaturan proxy npm jika berada di balik firewall
  • Firewall memblokir: Periksa apakah perangkat lunak keamanan memblokir unduhan paket
Persyaratan Sistem
  • Versi Node.js: Pastikan memenuhi ^22.23.4 || ^24.22.1 || >=26.12.1 dengan node --version
  • Perbarui Node.js: Pertimbangkan versi LTS terbaru jika mengalami masalah kompatibilitas
  • Manajer paket: Pastikan npm/pnpm berfungsi: npm --version
Masalah Khusus IDE
  • Lokasi file konfigurasi: Periksa kembali jalurnya untuk OS Anda
  • Kesalahan sintaks: Validasi sintaks JSON di file konfigurasi Anda
  • Log konsol: Periksa konsol pengembang IDE untuk mengetahui kesalahan spesifik
  • Coba IDE lain: Uji di editor lain yang didukung untuk mengisolasi masalah
Masalah Proses

Proses macet — hentikan proses MCP yang ada:

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

# Windows:
taskkill /f /im node.exe

Konflik port: Mulai ulang IDE jika koneksi tampak terblokir.

Debugging Lanjutan
  • Uji paket secara langsung: npx @circleci/mcp-server-circleci@latest --help
  • Pencatatan log terperinci: DEBUG=* npx @circleci/mcp-server-circleci@latest
  • Alternatif Docker: Coba instalasi Docker jika npx terus-menerus gagal

Masih membutuhkan bantuan?

  1. Periksa GitHub Issues 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 deployment 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. Build proyek:

    pnpm build

Membangun Kontainer Docker

Anda dapat membangun kontainer Docker secara lokal menggunakan:

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

Ini akan membuat image Docker dengan tag circleci:mcp-server-circleci yang dapat Anda gunakan dengan klien MCP apa pun.

Mode stdio lokal (satu developer, 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 Self-Managed Remote MCP Server.

Pengembangan dengan MCP Inspector

Cara termudah untuk mengembangkan MCP Server secara iteratif adalah menggunakan MCP inspector. Pelajari lebih lanjut tentang MCP inspector di https://modelcontextprotocol.io/docs/tools/inspector

  1. Mulai server pengembangan:

    pnpm watch # Keep this running in one terminal

  2. Di terminal terpisah, jalankan inspector:

    pnpm inspector

  3. Konfigurasikan lingkungan:

    • Tambahkan CIRCLECI_TOKEN Anda ke bagian Environment Variables di UI inspector
    • Token harus memiliki akses baca ke proyek CircleCI Anda
    • Atur CircleCI Base URL secara opsional (default-nya https://circleci.com)

Pengujian

  • Jalankan rangkaian pengujian:

    pnpm test

  • Jalankan pengujian dalam mode watch selama pengembangan:

    pnpm test:watch

Untuk panduan kontribusi yang lebih terperinci, lihat CONTRIBUTING.md