CircleCI
resmiYapay zeka ajanlarının CircleCI'dan gelen derleme hatalarını düzeltmesini sağlar.
CircleCI MCP ile neler yapabilirsiniz?
- Yapılandırmayı doğrula — Asistandan
.circleci/config.ymldosyanızı doğrulamasını veconfig_helperaracılığıyla sözdizimi ve anlamsal hatalar hakkında rehberlik almasını isteyin. - Derleme hatalarını teşhis et —
get_build_failure_logsile bir CircleCI derlemesinden ayrıntılı hata günlüklerini alın. - Kararsız testleri bulun —
find_flaky_testsile bir projenin test yürütme geçmişini analiz ederek kararsız testleri belirleyin. - İşlem hattı durumunu kontrol edin —
get_latest_pipeline_statuskullanarak bir dal için en son işlem hattının durumunu alın. - İş akışlarını yeniden çalıştırın —
rerun_workflowile bir iş akışını baştan veya başarısız işten yeniden çalıştırın. - İşlem hatlarını tetikleyin —
run_pipelineverun_rollback_pipelinekullanarak bir işlem hattı çalıştırın veya bir proje geri alımını tetikleyin.
Dokümantasyon
[!IMPORTANT] Bu paket kullanımdan kaldırılmıştır. Lütfen geçiş yapın.
@circleci/mcp-server-circleciartık yeni özellik çalışması almıyor. Bunun yerine CircleCI'nin barındırılan MCP sunucusunu veya CircleCI CLI MCP'yi kullanın — bkz. CircleCI MCP genel bakış.Bu depo arşivlenecektir. Mevcut sürümler npm'den yüklenebilir olmaya devam edecek, ancak CircleCI Kişisel API Token'ı tutan bakımı yapılmayan bir sunucuyu çalıştırmanız önerilmez.
Kendi yönettiğiniz uzak taşıyıcıyı (
start=remote) çalıştırıyorsanız önce geçiş yapın: barındırılan sunucu bunun doğrudan yerine geçer ve kuruluşunuzun token'ına aracılık eden, ağa açık bir hizmeti işletme ihtiyacını ortadan kaldırır.
CircleCI MCP Server
Model Context Protocol (MCP), büyük dil modelleri (LLM'ler) ile harici sistemler arasındaki bağlamı yönetmek için yeni, standartlaştırılmış bir protokoldür. Bu depoda CircleCI için bir MCP Sunucusu sunuyoruz.
CircleCI ile doğal dil kullanarak etkileşim kurmak için Cursor, Windsurf, Copilot, Claude veya MCP uyumlu herhangi bir istemciyi kullanın — IDE'nizden ayrılmadan.
Araçlar
| Araç | Açıklama |
|---|---|
config_helper | CircleCI yapılandırmanızı doğrulayın ve rehberlik alın |
download_usage_api_data | CircleCI Usage API'sinden kullanım verilerini indirin |
find_flaky_tests | Test yürütme geçmişini analiz ederek kararsız testleri belirleyin |
find_underused_resource_classes | Hesaplama kaynakları yetersiz kullanılan işleri bulun |
get_build_failure_logs | CircleCI derlemelerinden ayrıntılı hata günlüklerini alın |
get_job_test_results | CircleCI işleri için test meta verilerini ve sonuçlarını alın |
get_latest_pipeline_status | Bir dal için en son işlem hattının durumunu alın |
list_artifacts | Bir CircleCI işi tarafından üretilen yapıtları listeleyin |
list_component_versions | Bir CircleCI bileşeni için tüm sürümleri listeleyin |
list_followed_projects | Takip ettiğiniz tüm CircleCI projelerini listeleyin |
rerun_workflow | Bir iş akışını baştan veya başarısız işten yeniden çalıştırın |
run_pipeline | Çalıştırmak üzere bir işlem hattı tetikleyin |
run_rollback_pipeline | Bir proje için geri alma tetikleyin |
Kurulum
Ekip / merkezi dağıtım: Kuruluşunuz için geliştirici başına veya paylaşılan CircleCI token'larıyla tek bir paylaşılan uzak sunucu (Kubernetes, Docker vb.) çalıştırmak için bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu.
Cursor
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm - Docker: Docker
Yerel MCP Sunucusunda NPX Kullanma
Cursor MCP yapılandırmanıza aşağıdakini ekleyin:
{
"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_URListeğe bağlıdır — yalnızca şirket içi müşteriler için gereklidir.MAX_MCP_OUTPUT_LENGTHisteğe bağlıdır — MCP yanıtları için maksimum çıktı uzunluğu (varsayılan: 50000).
Yerel MCP Sunucusunda Docker Kullanma
Cursor MCP yapılandırmanıza aşağıdakini ekleyin:
{
"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"
}
}
}
}
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu. Kullanıcı başına istemci yapılandırmasını kullanın ve Cursor MCP yapılandırmanıza ekleyin (Cursor Settings → MCP).
VS Code
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm - Docker: Docker
Yerel MCP Sunucusunda NPX Kullanma
Projenizdeki .vscode/mcp.json dosyasına aşağıdakini ekleyin:
{
"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}"
}
}
}
}
💡 Girdiler sunucunun ilk başlatılmasında sorulur, ardından VS Code tarafından güvenli şekilde saklanır.
Yerel MCP Sunucusunda Docker Kullanma
Projenizdeki .vscode/mcp.json dosyasına aşağıdakini ekleyin:
{
"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}"
}
}
}
}
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu. .vscode/mcp.json içinde kullanıcı başına istemci yapılandırmasını kullanın.
Claude Desktop
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm - Docker: Docker
Yerel MCP Sunucusunda NPX Kullanma
claude_desktop_config.json dosyanıza aşağıdakini ekleyin:
{
"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"
}
}
}
}
Yerel MCP Sunucusunda Docker Kullanma
claude_desktop_config.json dosyanıza aşağıdakini ekleyin:
{
"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"
}
}
}
}
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu. Claude Desktop ve CLI istemcileri bölümünde gösterildiği gibi bir sarmalayıcı betik oluşturun, ardından claude_desktop_config.json dosyanızı ona yönlendirin.
Yapılandırma dosyanızı bulmak veya oluşturmak için Claude Desktop ayarlarını açın, sol kenar çubuğunda Developer seçeneğine tıklayın, ardından Edit Config seçeneğine tıklayın. Yapılandırma dosyası şu konumdadır:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Daha fazla bilgi için: https://modelcontextprotocol.io/quickstart/user
Claude Code
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm - Docker: Docker
Yerel MCP Sunucusunda NPX Kullanma
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest
Yerel MCP Sunucusunda Docker Kullanma
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
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu ve oradaki Claude Code istemci kurulumu.
Windsurf
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm - Docker: Docker
Yerel MCP Sunucusunda NPX Kullanma
Windsurf mcp_config.json dosyanıza aşağıdakini ekleyin:
{
"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"
}
}
}
}
Yerel MCP Sunucusunda Docker Kullanma
Windsurf mcp_config.json dosyanıza aşağıdakini ekleyin:
{
"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"
}
}
}
}
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu. Windsurf mcp_config.json dosyanızda kullanıcı başına istemci yapılandırmasını kullanın.
Daha fazla bilgi için: https://docs.windsurf.com/windsurf/mcp
Amazon Q Developer CLI
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm
Amazon Q Developer'da MCP istemci yapılandırması, mcp.json adlı bir dosyada JSON biçiminde saklanır. İki düzeyde yapılandırma desteklenir:
- Genel:
~/.aws/amazonq/mcp.json— tüm çalışma alanları için geçerlidir - Çalışma alanı:
.amazonq/mcp.json— geçerli çalışma alanına özeldir
Her iki dosya da mevcutsa içerikleri birleştirilir. Çakışma durumunda çalışma alanı yapılandırması önceliklidir.
Yerel MCP Sunucusunda NPX Kullanma
~/.aws/amazonq/mcp.json dosyasını düzenleyin veya .amazonq/mcp.json dosyasını aşağıdakiyle oluşturun:
{
"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
}
}
}
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu. Claude Desktop ve CLI istemcileri bölümünde gösterildiği gibi bir sarmalayıcı betik kullanın, ardından q mcp add ile kaydedin.
IDE'de Amazon Q Developer
Ön koşullar:
- CircleCI Kişisel API token'ı (daha fazla bilgi)
- NPX: Node.js
^22.23.4 || ^24.22.1 || >=26.12.1ve pnpm
Yerel MCP Sunucusunda NPX Kullanma
~/.aws/amazonq/mcp.json dosyasını düzenleyin veya .amazonq/mcp.json dosyasını aşağıdakiyle oluşturun:
{
"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
}
}
}
Kendi Yönettiğiniz Uzak MCP Sunucusunu Kullanma
Bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu. Claude Desktop ve CLI istemcileri bölümünde gösterildiği gibi bir sarmalayıcı betik kullanın, ardından MCP yapılandırma arayüzü aracılığıyla ekleyin:
- MCP yapılandırma arayüzüne erişin
- + simgesini seçin
- Kapsam seçin: global veya local
- Bir ad girin (ör.
circleci-remote-mcp) - Taşıyıcı protokolünü seçin: stdio
- Betiğinize giden komut yolunu girin
- Save seçeneğine tıklayın
Smithery
CircleCI MCP Server'ı Claude Desktop için Smithery aracılığıyla otomatik olarak yüklemek için:
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
Kendi Yönettiğiniz Uzak MCP Sunucusu
Ekibinizin tek bir dağıtımı paylaşması için MCP sunucusunu merkezi olarak (örneğin Kubernetes veya Docker üzerinde) çalıştırın. Geliştiricilerin kimlik doğrulamasını nasıl yapacağını seçin:
Bir dağıtım modu seçin
| Mod | Ne zaman kullanılır | Sunucu kurulumu | İstemci kurulumu | CircleCI denetim izi |
|---|---|---|---|---|
| Kullanıcı başına token'lar (önerilen) | SSO destekli Kişisel API Token'ları olan ekipler | REQUIRE_REQUEST_TOKEN=true, sunucu PAT'i yok | Her geliştirici kendi PAT'ini iletir | Geliştirici başına |
| Paylaşılan token (geçici) | Hızlı kullanıma alma, tek hizmet kimliği uygun | Sunucuda CIRCLECI_TOKEN, REQUIRE_REQUEST_TOKEN=false (açık devre dışı bırakma) | Kimlik doğrulama başlığı gerekmez | Tek paylaşılan kimlik |
Güvenlik: Uzak modda istek kimlik doğrulaması varsayılan olarak açıktır. Paylaşılan token modu bunu devre dışı bırakır (
REQUIRE_REQUEST_TOKEN=false), böylece her çağıran, kimlik bilgisi olmadan sunucununCIRCLECI_TOKENkimliği olarak hareket edebilir — rastgele yapılandırmayla işlem hatlarını tetiklemek dahil. Yalnızca tamamen güvendiğiniz bir ağda etkinleştirin ve aksi halde kullanıcı başına token'ları tercih edin. Girişte TLS sonlandırma şifreleme sağlar, kimlik doğrulama sağlamaz.Bu kombinasyon genel bir arayüzde güvensiz olduğundan, sunucu
REQUIRE_REQUEST_TOKEN=falseile döngü dışı bir bağlama adresiyle birleştirildiğinde, riskiMCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=trueile açıkça kabul etmediğiniz sürece başlamayı reddeder.Host/Originkontrolü kimlik doğrulamanın yerine geçmez — aşağıdaki DNS yeniden bağlama korumasına bakın.
1. Sunucuyu dağıtın
Her iki mod da uzak HTTP modunu (start=remote) kullanır. 8000 portunu (veya seçtiğiniz portu) yayımlayın.
Kullanıcı başına token'lar (önerilen) — localhost'tan mcp-remote aracılığıyla erişilir:
docker run --rm -p 8000:8000 \
-e start=remote \
-e port=8000 \
-e REQUIRE_REQUEST_TOKEN=true \
circleci/mcp-server-circleci
Kullanıcı başına token'lar (önerilen) — genel bir ana bilgisayar adından mcp-remote aracılığıyla erişilir:
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
Paylaşılan token (geçici) — genel bir ana bilgisayar adından mcp-remote aracılığıyla erişilir:
Bu mod, kuruluşun PAT'ini kimlik bilgisi olmadan her çağırana sunduğundan, yalnızca yayımlanan portun güvenilmeyen ağlardan erişilemez olduğu yerlerde çalıştırılmalı ve bunu açıkça kabul etmelisiniz, aksi halde sunucu başlamayı reddeder:
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
Bunun yerine portun önüne kimlik doğrulama koymayı tercih edin — SSO, mTLS veya bir API anahtarı gerektiren bir giriş — ya da yukarıdaki kullanıcı başına token'lara geçin.
Ortam değişkenleri:
| Değişken | Açıklama |
|---|---|
start=remote | stdio yerine HTTP+SSE MCP sunucusunu başlatır |
port | Konteyner içinde dinleme portu (varsayılan: 8000) |
REQUIRE_REQUEST_TOKEN | Authorization: Bearer veya Circle-Token başlığı olmayan istekleri reddeder. Varsayılan olarak zorunludur; kimlik doğrulamasız isteklere izin vermek için REQUIRE_REQUEST_TOKEN=false olarak ayarlayın (paylaşılan belirteç modu) |
CIRCLECI_TOKEN | Kullanıcı başına başlıklar gönderilmediğinde tüm istekler için paylaşılan yedek PAT |
CIRCLECI_BASE_URL | İsteğe bağlı — yalnızca şirket içi kurulumlar için gereklidir (varsayılan: https://circleci.com) |
DISABLE_TELEMETRY=true | Kullanım metrikleri dışa aktarımından çıkış yap |
MCP_ALLOWED_HOSTS | İzin verilecek ek Host başlık değerlerinin virgülle ayrılmış listesi (ör. my-mcp.example.com,my-mcp.example.com:443). Loopback ana bilgisayar adlarına her zaman izin verilir. Loopback dışı her dağıtım için gereklidir. |
MCP_ALLOWED_ORIGINS | İzin verilecek ek Origin başlık değerlerinin virgülle ayrılmış listesi (ör. https://my-app.example.com). Loopback kaynaklarına her zaman izin verilir. Yalnızca bir tarayıcı bu sunucuya doğrudan ulaştığında (mcp-remote üzerinden değil) gereklidir. |
MCP_BIND_HOST | Bağlanılacak ağ arayüzü (varsayılan: 0.0.0.0). Yalnızca loopback ile sınırlamak için 127.0.0.1 olarak ayarlayın (Docker -p port eşlemesiyle uyumlu değildir). |
MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS | Loopback dışı bir bağlama adresinde REQUIRE_REQUEST_TOKEN=false ile başlamak için gereklidir (=true). Porta ulaşabilen herhangi bir eşin, kimlik bilgisi olmadan sunucunun CIRCLECI_TOKEN kimliği olarak davrandığını kabul eder. İstek belirteçleri gerektiğinde etkisi yoktur. |
MCP_FILE_OUTPUT_ROOTS | Dosya okuma/yazma araçlarının kullanabileceği ek dizinlerin virgülle ayrılmış listesi (ör. /srv/reports,/data/exports). Çalışma dizini, ana dizin ve geçici dizine her zaman izin verilir. Aşağıdaki nota bakın. |
Dosya çıktısı konumları (hem stdio hem de uzak taşıyıcılar için geçerlidir): Bir dosya sistemi yolu kabul eden araçlar —
get_build_failure_logs(outputDir),download_usage_api_data(outputDir) vefind_underused_resource_classes(csvFilePath) — yalnızca sunucunun çalışma dizini, kullanıcının ana dizini ve sistem geçici dizini içinde okuyup yazabilir. Bu kökler içinde, gizli yapılandırma dizinleri (~/.ssh,~/.aws,~/.config,.git, …),node_modulesve başlatma aracısı dizinleri reddedilir; izin verilen köklerin dışına çözümlenen sembolik bağlantılar da reddedilir. Sistem dizinleri (/etc,/usr,/bin,/System,/Library,%SystemRoot%, …) koşulsuz olarak reddedilir ve yeniden etkinleştirilemez. Çıktı dosyaları hiçbir zaman sembolik bağlantı üzerinden yazılmaz.Çalışma kopyanız bu köklerin dışındaysa — bir konteynerde
/workspace,/srv,/opt,/Volumes/workgibi ikincil bir birim —MCP_FILE_OUTPUT_ROOTSdeğişkenini o dizine ayarlayın, aksi takdirde bu yollar reddedilir. Bir stdio sunucusu için çalışma dizini genellikle zaten proje köküdür, bu nedenle yapılandırma gerekmez. Bu, yolların yerel kullanıcı yerine ağ istemcilerinden geldiği uzak taşıyıcı için en çok önemlidir.
DNS yeniden bağlama koruması (kimlik doğrulama değil): Uzak taşıyıcı, her
/mcpisteğindeHostbaşlığını doğrular. Varsayılan olarak yalnızca loopback adresleri (localhost,127.0.0.1,[::1]) kabul edilir. Genel dağıtımlarMCP_ALLOWED_HOSTSdeğişkenini istemcilerin kullandığı ana bilgisayar adına ayarlamalıdır, aksi takdirde tüm/mcpistekleri403 Forbiddenalır./pingsağlık kontrolü uç noktası korunmaz, böylece yük dengeleyici yoklamalarıHostne olursa olsun çalışmaya devam eder.Tarayıcılar tarafından gönderilen
Originbaşlığı da mevcut olduğunda doğrulanır.mcp-remotegibi tarayıcı olmayan istemciler hiçbir zamanOrigingöndermez, bu nedenle bu kontrolden etkilenmezler.Bu kontrol bir erişim denetimi değildir ve öyleymiş gibi güvenilmemelidir. Her iki başlık da çağıran tarafından seçilir, bu nedenle tarayıcı olmayan herhangi bir istemci — curl, bir betik, ham bir soket — izin verilen bir
HostgönderipOriginbaşlığını atlayarak bu kontrolü karşılayabilir. Tek amacı, bir tarayıcının saldırgan kontrollü DNS tarafından sunucuya yönlendirilmesini engellemektir; bu da DNS yeniden bağlama tehdididir. Çağıranların kimliğini doğrulamakREQUIRE_REQUEST_TOKEN(veya portun önündeki kimlik doğrulayan bir proxy) işidir. BirOriginbaşlığı zorunlu kılmak, hiçbir saldırganı durdurmadan her meşru CLI istemcisini bozar.Ters proxy arkasında: Proxy'niz
Hostbaşlığını arka uç adresine yeniden yazıyorsa (nginx'in varsayılanı), orijinal ana bilgisayar adını iletmek içinproxy_set_header Host $host;ekleyin, ardındanMCP_ALLOWED_HOSTSdeğişkenini o genel ana bilgisayar adına ayarlayın. Alternatif olarak,MCP_ALLOWED_HOSTSdeğişkenini proxy'nin ilettiği ana bilgisayar adına ayarlayın.
Sunucu, istek başına belirteçleri şu yollarla kabul eder:
Authorization: Bearer <circleci-pat>Circle-Token: <circleci-pat>
Bir istemci bir başlık belirteci gönderirse, bu belirteç sunucudaki CIRCLECI_TOKEN değerine göre önceliklidir.
Bir istek sırasında kaydedilen telemetri metrikleri, o istekle aynı belirteç kullanılarak dışa aktarılır.
2. İstemcileri yapılandırın
Çoğu MCP istemcisi yalnızca yerel (stdio) süreçleri destekler. Bunları uzak sunucunuza bağlamak için üçüncü taraf bir stdio-HTTP köprüsü olan mcp-remote kullanın.
URL şeması: Yerel test için
--allow-httpile birliktehttp://localhost:8000/mcpkullanın. Üretimde TLS'i giriş/yük dengeleyicinizde sonlandırın ve--allow-httpolmadanhttps://your-host/mcpkullanın.
Windows:
--headerdeğerlerinde iki nokta üst üste işaretinin etrafındaki boşluklardan kaçının. TamBearer <token>değerini bir ortam değişkenine koyun.
Güvenlik: Örnekler kolaylık sağlamak için
npxkullanır. Üretim veya ekip dağıtımları için MCP yapılandırmanızda belirli bir sürümü sabitleyin (örneğinmcp-remoteyerinemcp-remote@0.1.38).0.1.16altındaki sürümleri kullanmayın (CVE-2025-6514).
İstemci yapılandırması: kullanıcı başına belirteçler
Her geliştirici, her istekte kendi CircleCI Kişisel API Belirtecini iletir:
{
"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}"
}
}
}
}
http://localhost:8000/mcp yerine ekibinizin sunucu URL'sini koyun. Cursor ve VS Code ${input:...} istemlerini destekler; diğer istemciler AUTH_HEADER değişkenini doğrudan ayarlayabilir.
İstemci yapılandırması: paylaşılan belirteç
Sunucuda CIRCLECI_TOKEN ayarlanmış ve REQUIRE_REQUEST_TOKEN=false ile başlatılmışsa (istek kimlik doğrulaması varsayılan olarak açıktır ve açıkça devre dışı bırakılmalıdır; ayrıca loopback dışı bir bağlama ek olarak MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true gerektirir), istemcilerin belirteç göndermesine gerek yoktur:
{
"mcpServers": {
"circleci-mcp-server-remote": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp",
"--allow-http"
]
}
}
}
Claude Desktop ve CLI istemcileri
Bir sarmalayıcı betik oluşturun (ör. 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}"
Çalıştırılabilir yapın (chmod +x circleci-remote-mcp.sh), ardından MCP yapılandırmanızdan buna başvurun:
{
"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}"
Paylaşılan belirteçli sunucu kullanırken --header ve AUTH_HEADER değişkenlerini atlayın.
3. Dağıtımı doğrulayın
# 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
İş başında izleyin
Örnek: "Dallamdaki en son başarısız işlem hattını bul ve günlükleri al" — daha fazla örnek için wiki sayfasına bakın.
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
Araç Ayrıntıları
config_helper
Rehberlik ve doğrulama sağlayarak CircleCI yapılandırma görevlerine yardımcı olur.
.circleci/config.ymldosyanızı sözdizimi ve anlamsal hatalar açısından doğrular- Ayrıntılı doğrulama sonuçları ve yapılandırma önerileri sunar
- Örnek: "CircleCI yapılandırmamı doğrula"
download_usage_api_data
Belirli bir kuruluş için CircleCI Kullanım API'sinden kullanım verilerini indirir. Esnek tarih girişini kabul eder (ör. "Mart 2025" veya "geçen ay"). Yalnızca bulut özelliğidir.
Seçenek 1: Şunları sağlayarak yeni bir dışa aktarma işi başlatın:
orgId,startDate,endDate(en fazla 32 gün),outputDir
Seçenek 2: Şunları sağlayarak mevcut bir dışa aktarma işini kontrol edin/indirin:
orgId,jobId,outputDir
Belirtilen zaman aralığı için CircleCI kullanım verilerini içeren bir CSV dosyası döndürür.
[!NOTE] Kullanım verileri, maliyet optimizasyonu analizi için
find_underused_resource_classesaracına aktarılabilir.
find_flaky_tests
Test yürütme geçmişini analiz ederek CircleCI projenizdeki kararsız testleri belirler. CircleCI'daki kararsız test algılama özelliğinden yararlanır.
Bu araç üç şekilde kullanılabilir:
-
Proje Kısa Adı Kullanarak (Önerilen):
- Önce projelerinizi almak için
list_followed_projectskullanın, ardından: - Örnek: "my-project için kararsız testleri al"
- Önce projelerinizi almak için
-
CircleCI Proje URL'si Kullanarak:
- Örnek: "https://app.circleci.com/pipelines/github/org/repo içindeki kararsız testleri bul"
-
Yerel Proje Bağlamı Kullanarak:
- Çalışma alanı kökü ve git uzak URL'si sağlayarak yerel çalışma alanınızdan çalışır
- Örnek: "Mevcut projemdeki kararsız testleri bul"
Çıktı modları:
- Metin (varsayılan): Kararsız test ayrıntılarını metin biçiminde döndürür
- Dosya (
FILE_OUTPUT_DIRECTORYortam değişkeni gerektirir): Kararsız test ayrıntılarını içeren bir dizin oluşturur
find_underused_resource_classes
Ortalama veya maksimum CPU/RAM kullanımı belirli bir eşiğin (varsayılan: %40) altında olan işleri bulmak için bir CircleCI kullanım verisi CSV dosyasını analiz eder.
download_usage_api_data aracından elde edilen bir CSV dosyası sağlayın.
Proje ve iş akışına göre düzenlenmiş, yeterince kullanılmayan işlerin markdown listesini döndürür — maliyet optimizasyonu fırsatlarını belirlemek için kullanışlıdır.
get_build_failure_logs
CircleCI derlemelerinden ayrıntılı hata günlüklerini alır. Bu araç üç şekilde kullanılabilir:
-
Proje Kısa Adı ve Dal Kullanarak (Önerilen):
- Önce projelerinizi almak için
list_followed_projectskullanın, ardından: - Örnek: "my-project için main dalındaki derleme hatalarını al"
- Önce projelerinizi almak için
-
CircleCI URL'leri Kullanarak:
- Doğrudan başarısız bir iş URL'si veya işlem hattı URL'si sağlayın
- Örnek: "https://app.circleci.com/pipelines/github/org/repo/123 adresinden günlükleri al"
-
Yerel Proje Bağlamı Kullanarak:
- Çalışma alanı kökü, git uzak URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır
- Örnek: "Mevcut dallamdaki en son başarısız işlem hattını bul"
Araç, şunları içeren biçimlendirilmiş günlükleri döndürür:
- İş adları
- Adım adım yürütme ayrıntıları
- Hata mesajları ve bağlam
get_job_test_results
CircleCI işleri için test meta verilerini alır; IDE'nizden ayrılmadan test sonuçlarını analiz etmenizi sağlar. Bu araç üç şekilde kullanılabilir:
-
Proje Kısa Adı ve Dal Kullanarak (Önerilen):
- Örnek: "my-project için main dalındaki test sonuçlarını al"
-
CircleCI URL'si Kullanarak:
- İş URL'si:
https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 - İş akışı URL'si:
https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def - İşlem hattı URL'si:
https://app.circleci.com/pipelines/github/org/repo/123
- İş URL'si:
-
Yerel Proje Bağlamı Kullanarak:
- Çalışma alanı kökü, git uzak URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır
Araç şunları döndürür:
- Tüm testlerin özeti (toplam, başarılı, başarısız)
- Başarısız testler hakkında ayrıntılı bilgi: ad, sınıf, dosya, hata mesajı, süre
- Zamanlamayla birlikte başarılı testlerin listesi
- Test sonucuna göre filtreleme
[!NOTE] Test meta verileri CircleCI yapılandırmanızda yapılandırılmalıdır. Kurulum talimatları için Test Verilerini Toplama sayfasına bakın.
get_latest_pipeline_status
Belirli bir dal için en son pipeline'ın durumunu alır. Bu araç üç şekilde kullanılabilir:
-
Proje Slug'ı ve Dal Kullanarak (Önerilen):
- Örnek: "my-project için main dalındaki en son pipeline'ın durumunu al"
-
CircleCI Proje URL'si Kullanarak:
- Örnek: "https://app.circleci.com/pipelines/github/org/repo için en son pipeline'ın durumunu al"
-
Yerel Proje Bağlamını Kullanarak:
- Çalışma alanı kök dizini, git remote URL'si ve dal adı sağlanarak yerel çalışma alanınızdan çalışır
Örnek çıktı:
---
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
Bir CircleCI job'ı tarafından üretilen artifact'ların listesini alır. Bu araç üç şekilde kullanılabilir:
-
Proje Slug'ı ve Dal Kullanarak (Önerilen):
- Önce projelerinizi almak için
list_followed_projectskullanın, ardından: - Örnek: "my-project için main dalındaki artifact'ları listele"
- Önce projelerinizi almak için
-
CircleCI URL'si Kullanarak:
- Job URL'si:
https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789 - Workflow URL'si:
https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def - Pipeline URL'si:
https://app.circleci.com/pipelines/gh/organization/project/123
- Job URL'si:
-
Yerel Proje Bağlamını Kullanarak:
- Çalışma alanı kök dizini, git remote URL'si ve dal adı sağlanarak yerel çalışma alanınızdan çalışır
Şunlar için kullanışlıdır:
- Build artifact'ları (ikili dosyalar, raporlar, loglar) için indirme URL'lerini bulma
- Bir pipeline çalıştırması tarafından hangi artifact'ların üretildiğini kontrol etme
list_component_versions
Bir ortamdaki belirli bir CircleCI bileşeni için tüm sürümleri listeler. Dağıtım durumu, commit bilgileri ve zaman damgalarını içerir.
Sağlanmadıysa araç sizden bileşeni ve ortamı seçmenizi ister.
Şunlar için kullanışlıdır:
- Şu anda hangi sürümün canlı olduğunu belirleme
- Geri alma işlemleri için hedef sürümleri seçme
- Dağıtım ayrıntılarını (pipeline, workflow, job) alma
list_followed_projects
Kullanıcının CircleCI'da takip ettiği tüm projeleri listeler.
- Erişiminiz olan tüm projeleri
projectSlugile birlikte gösterir - Örnek: "CircleCI projelerimi listele"
Örnek çıktı:
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)
[!NOTE] Diğer birçok CircleCI aracı için (proje adı değil)
projectSluggereklidir.
rerun_workflow
Bir workflow'u başlangıcından veya başarısız olan job'dan yeniden çalıştırır.
Yeni oluşturulan workflow'un kimliğini ve onu izlemek için bir bağlantı döndürür.
run_pipeline
Bir pipeline'ın çalışmasını tetikler. Bu araç üç şekilde kullanılabilir:
-
Proje Slug'ı ve Dal Kullanarak (Önerilen):
- Örnek: "my-project için main dalında pipeline'ı çalıştır"
-
CircleCI URL'si Kullanarak:
- Pipeline URL'si, Workflow URL'si, Job URL'si veya dallı Proje URL'si
- Örnek: "https://app.circleci.com/pipelines/github/org/repo/123 için pipeline'ı çalıştır"
-
Yerel Proje Bağlamını Kullanarak:
- Çalışma alanı kök dizini, git remote URL'si ve dal adı sağlanarak yerel çalışma alanınızdan çalışır
Araç, pipeline çalıştırmasını izlemek için bir bağlantı döndürür.
run_rollback_pipeline
Bir CircleCI projesi için geri alma işlemini tetikler. Araç sizi etkileşimli olarak şu adımlardan geçirir:
- Proje Seçimi — aralarından seçim yapmanız için takip edilen projeleri listeler
- Ortam Seçimi — mevcut ortamları listeler (yalnızca bir tane varsa otomatik seçer)
- Bileşen Seçimi — mevcut bileşenleri listeler (yalnızca bir tane varsa otomatik seçer)
- Sürüm Seçimi — mevcut sürümleri görüntüler; geri alma için hedefi siz seçersiniz
- Geri Alma Modu Algılama — bir geri alma pipeline'ının yapılandırılıp yapılandırılmadığını kontrol eder
- Geri Almayı Yürüt — iki seçenek:
- Pipeline Geri Alma: geri alma pipeline'ını tetikler
- Workflow Yeniden Çalıştırma: workflow kimliğini kullanarak önceki bir workflow'u yeniden çalıştırır
- Onay — yürütmeden önce özetler ve onay ister
Sorun Giderme
Hızlı Çözümler
En yaygın sorunlar:
-
Paket önbelleklerini temizleyin:
npx clear-npx-cache npm cache clean --force -
En son sürüme zorlayın: Yapılandırmanıza
@latestekleyin:"args": ["-y", "@circleci/mcp-server-circleci@latest"] -
IDE'nizi tamamen yeniden başlatın (yalnızca pencereyi yeniden yüklemekle kalmayın)
Kimlik Doğrulama Sorunları
- Geçersiz token hataları: Kişisel API Token'ları sayfasında
CIRCLECI_TOKENdeğerinizi doğrulayın - İzin hataları: Token'ın projelerinize okuma erişimi olduğundan emin olun
- Ortam değişkenleri yüklenmiyor:
echo $CIRCLECI_TOKEN(Mac/Linux) veyaecho %CIRCLECI_TOKEN%(Windows) ile test edin
Bağlantı ve Ağ Sorunları
- Temel URL:
CIRCLECI_BASE_URLdeğerininhttps://circleci.comolduğunu doğrulayın - Kurumsal ağlar: Güvenlik duvarı arkasındaysanız npm proxy ayarlarını yapılandırın
- Güvenlik duvarı engellemesi: Güvenlik yazılımının paket indirmelerini engelleyip engellemediğini kontrol edin
Sistem Gereksinimleri
- Node.js sürümü:
node --versionile^22.23.4 || ^24.22.1 || >=26.12.1gereksinimini karşıladığından emin olun - Node.js'i güncelleyin: Uyumluluk sorunları yaşıyorsanız en son LTS sürümünü düşünün
- Paket yöneticisi: npm/pnpm'in çalıştığını doğrulayın:
npm --version
IDE'ye Özgü Sorunlar
- Yapılandırma dosyası konumu: İşletim sisteminiz için yolu iki kez kontrol edin
- Sözdizimi hataları: Yapılandırma dosyanızdaki JSON sözdizimini doğrulayın
- Konsol logları: Belirli hatalar için IDE geliştirici konsolunu kontrol edin
- Farklı bir IDE deneyin: Sorunu izole etmek için desteklenen başka bir düzenleyicide test edin
Süreç Sorunları
Takılı kalan süreçler — mevcut MCP süreçlerini sonlandırın:
# Mac/Linux:
pkill -f "mcp-server-circleci"
# Windows:
taskkill /f /im node.exe
Port çakışmaları: Bağlantı engellenmiş görünüyorsa IDE'nizi yeniden başlatın.
Gelişmiş Hata Ayıklama
- Paketi doğrudan test edin:
npx @circleci/mcp-server-circleci@latest --help - Ayrıntılı günlük kaydı:
DEBUG=* npx @circleci/mcp-server-circleci@latest - Docker yedeği: npx sürekli başarısız olursa Docker kurulumunu deneyin
Hâlâ yardıma mı ihtiyacınız var?
- Benzer sorunlar için GitHub Issues sayfasını kontrol edin
- Sorun bildirirken işletim sisteminizi, Node sürümünüzü ve IDE'nizi belirtin
- IDE konsolundaki ilgili hata mesajlarını paylaşın
Telemetri
Sunucu, araç kullanımını izlemek için OpenTelemetry metriklerini destekler. DISABLE_TELEMETRY=true ayarlamadığınız sürece metrikler dışa aktarılır. Uzak dağıtımlarda metrikler, istekle aynı token'ı kullanır (kullanıcı başına PAT veya paylaşılan sunucu PAT'i).
| Metrik | Açıklama |
|---|---|
circleci.mcp.tool.invocations | Araç çağırma sayısı |
circleci.mcp.tool.duration_ms | Milisaniye cinsinden yürütme süresi |
circleci.mcp.tool.errors | Hata sayısı |
Geliştirme
Başlarken
-
Depoyu klonlayın:
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci -
Bağımlılıkları yükleyin:
pnpm install -
Projeyi derleyin:
pnpm build
Docker Container'ı Derleme
Docker container'ını yerel olarak şu şekilde derleyebilirsiniz:
docker build -t circleci:mcp-server-circleci .
Bu, herhangi bir MCP istemcisiyle kullanabileceğiniz circleci:mcp-server-circleci olarak etiketlenmiş bir Docker imajı oluşturur.
Yerel stdio modu (tek geliştirici, token istemcide):
docker run --rm -i \
-e CIRCLECI_TOKEN=your-circleci-token \
-e CIRCLECI_BASE_URL=https://circleci.com \
circleci/mcp-server-circleci
Uzak mod (bir ekip için merkezi sunucu): bkz. Kendi Yönettiğiniz Uzak MCP Sunucusu.
MCP Inspector ile Geliştirme
MCP Sunucusu üzerinde yineleme yapmanın en kolay yolu MCP inspector'ı kullanmaktır. MCP inspector hakkında daha fazla bilgiyi şu adreste bulabilirsiniz: https://modelcontextprotocol.io/docs/tools/inspector
-
Geliştirme sunucusunu başlatın:
pnpm watch # Keep this running in one terminal -
Ayrı bir terminalde inspector'ı başlatın:
pnpm inspector -
Ortamı yapılandırın:
CIRCLECI_TOKENdeğerinizi inspector arayüzündeki Ortam Değişkenleri bölümüne ekleyin- Token'ın CircleCI projelerinize okuma erişimi olması gerekir
- İsteğe bağlı olarak CircleCI Temel URL'nizi ayarlayın (varsayılan olarak
https://circleci.com)
Test Etme
-
Test paketini çalıştırın:
pnpm test -
Geliştirme sırasında testleri izleme modunda çalıştırın:
pnpm test:watch
Daha ayrıntılı katkı yönergeleri için bkz. CONTRIBUTING.md