CircleCI

resmi

Yapay 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.yml dosyanızı doğrulamasını ve config_helper aracılığıyla sözdizimi ve anlamsal hatalar hakkında rehberlik almasını isteyin.
  • Derleme hatalarını teşhis et — get_build_failure_logs ile bir CircleCI derlemesinden ayrıntılı hata günlüklerini alın.
  • Kararsız testleri bulun — find_flaky_tests ile bir projenin test yürütme geçmişini analiz ederek kararsız testleri belirleyin.
  • İşlem hattı durumunu kontrol edin — get_latest_pipeline_status kullanarak bir dal için en son işlem hattının durumunu alın.
  • İş akışlarını yeniden çalıştırın — rerun_workflow ile bir iş akışını baştan veya başarısız işten yeniden çalıştırın.
  • İşlem hatlarını tetikleyin — run_pipeline ve run_rollback_pipeline kullanarak 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-circleci artı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

License: Apache 2.0 CircleCI npm

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_helperCircleCI yapılandırmanızı doğrulayın ve rehberlik alın
download_usage_api_dataCircleCI Usage API'sinden kullanım verilerini indirin
find_flaky_testsTest yürütme geçmişini analiz ederek kararsız testleri belirleyin
find_underused_resource_classesHesaplama kaynakları yetersiz kullanılan işleri bulun
get_build_failure_logsCircleCI derlemelerinden ayrıntılı hata günlüklerini alın
get_job_test_resultsCircleCI işleri için test meta verilerini ve sonuçlarını alın
get_latest_pipeline_statusBir dal için en son işlem hattının durumunu alın
list_artifactsBir CircleCI işi tarafından üretilen yapıtları listeleyin
list_component_versionsBir CircleCI bileşeni için tüm sürümleri listeleyin
list_followed_projectsTakip ettiğiniz tüm CircleCI projelerini listeleyin
rerun_workflowBir 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_pipelineBir 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:

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_URL isteğe bağlıdır — yalnızca şirket içi müşteriler için gereklidir. MAX_MCP_OUTPUT_LENGTH isteğ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:

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:

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:

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:

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:

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:

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:

  1. MCP yapılandırma arayüzüne erişin
  2. + simgesini seçin
  3. Kapsam seçin: global veya local
  4. Bir ad girin (ör. circleci-remote-mcp)
  5. Taşıyıcı protokolünü seçin: stdio
  6. Betiğinize giden komut yolunu girin
  7. 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

ModNe zaman kullanılırSunucu kurulumuİstemci kurulumuCircleCI denetim izi
Kullanıcı başına token'lar (önerilen)SSO destekli Kişisel API Token'ları olan ekiplerREQUIRE_REQUEST_TOKEN=true, sunucu PAT'i yokHer geliştirici kendi PAT'ini iletirGeliştirici başına
Paylaşılan token (geçici)Hızlı kullanıma alma, tek hizmet kimliği uygunSunucuda CIRCLECI_TOKEN, REQUIRE_REQUEST_TOKEN=false (açık devre dışı bırakma)Kimlik doğrulama başlığı gerekmezTek 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 sunucunun CIRCLECI_TOKEN kimliğ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=false ile döngü dışı bir bağlama adresiyle birleştirildiğinde, riski MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true ile açıkça kabul etmediğiniz sürece başlamayı reddeder. Host/Origin kontrolü 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şkenAçıklama
start=remotestdio yerine HTTP+SSE MCP sunucusunu başlatır
portKonteyner içinde dinleme portu (varsayılan: 8000)
REQUIRE_REQUEST_TOKENAuthorization: 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_TOKENKullanı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=trueKullanı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_HOSTBağ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_ACCESSLoopback 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_ROOTSDosya 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) ve find_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_modules ve 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/work gibi ikincil bir birim — MCP_FILE_OUTPUT_ROOTS değ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 /mcp isteğinde Host başlığını doğrular. Varsayılan olarak yalnızca loopback adresleri (localhost, 127.0.0.1, [::1]) kabul edilir. Genel dağıtımlar MCP_ALLOWED_HOSTS değişkenini istemcilerin kullandığı ana bilgisayar adına ayarlamalıdır, aksi takdirde tüm /mcp istekleri 403 Forbidden alır. /ping sağlık kontrolü uç noktası korunmaz, böylece yük dengeleyici yoklamaları Host ne olursa olsun çalışmaya devam eder.

Tarayıcılar tarafından gönderilen Origin başlığı da mevcut olduğunda doğrulanır. mcp-remote gibi tarayıcı olmayan istemciler hiçbir zaman Origin gö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 Host gönderip Origin baş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ğrulamak REQUIRE_REQUEST_TOKEN (veya portun önündeki kimlik doğrulayan bir proxy) işidir. Bir Origin başlığı zorunlu kılmak, hiçbir saldırganı durdurmadan her meşru CLI istemcisini bozar.

Ters proxy arkasında: Proxy'niz Host başlığını arka uç adresine yeniden yazıyorsa (nginx'in varsayılanı), orijinal ana bilgisayar adını iletmek için proxy_set_header Host $host; ekleyin, ardından MCP_ALLOWED_HOSTS değişkenini o genel ana bilgisayar adına ayarlayın. Alternatif olarak, MCP_ALLOWED_HOSTS değ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-http ile birlikte http://localhost:8000/mcp kullanın. Üretimde TLS'i giriş/yük dengeleyicinizde sonlandırın ve --allow-http olmadan https://your-host/mcp kullanın.

Windows: --header değerlerinde iki nokta üst üste işaretinin etrafındaki boşluklardan kaçının. Tam Bearer <token> değerini bir ortam değişkenine koyun.

Güvenlik: Örnekler kolaylık sağlamak için npx kullanır. Üretim veya ekip dağıtımları için MCP yapılandırmanızda belirli bir sürümü sabitleyin (örneğin mcp-remote yerine mcp-remote@0.1.38). 0.1.16 altı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.yml dosyanı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_classes aracı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:

  1. Proje Kısa Adı Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "my-project için kararsız testleri al"
  2. CircleCI Proje URL'si Kullanarak:

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

  1. Proje Kısa Adı ve Dal Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "my-project için main dalındaki derleme hatalarını al"
  2. CircleCI URL'leri Kullanarak:

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

  1. Proje Kısa Adı ve Dal Kullanarak (Önerilen):

    • Örnek: "my-project için main dalındaki test sonuçlarını al"
  2. 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
  3. 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:
  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Örnek: "my-project için main dalındaki en son pipeline'ın durumunu al"
  2. CircleCI Proje URL'si Kullanarak:

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

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "my-project için main dalındaki artifact'ları listele"
  2. 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
  3. 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 projectSlug ile 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) projectSlug gereklidir.

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:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Örnek: "my-project için main dalında pipeline'ı çalıştır"
  2. CircleCI URL'si Kullanarak:

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

  1. Proje Seçimi — aralarından seçim yapmanız için takip edilen projeleri listeler
  2. Ortam Seçimi — mevcut ortamları listeler (yalnızca bir tane varsa otomatik seçer)
  3. Bileşen Seçimi — mevcut bileşenleri listeler (yalnızca bir tane varsa otomatik seçer)
  4. Sürüm Seçimi — mevcut sürümleri görüntüler; geri alma için hedefi siz seçersiniz
  5. Geri Alma Modu Algılama — bir geri alma pipeline'ının yapılandırılıp yapılandırılmadığını kontrol eder
  6. 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
  7. Onay — yürütmeden önce özetler ve onay ister

Sorun Giderme

Hızlı Çözümler

En yaygın sorunlar:

  1. Paket önbelleklerini temizleyin:

    npx clear-npx-cache
    npm cache clean --force
    
  2. En son sürüme zorlayın: Yapılandırmanıza @latest ekleyin:

    "args": ["-y", "@circleci/mcp-server-circleci@latest"]
    
  3. 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_TOKEN değ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) veya echo %CIRCLECI_TOKEN% (Windows) ile test edin
Bağlantı ve Ağ Sorunları
  • Temel URL: CIRCLECI_BASE_URL değerinin https://circleci.com olduğ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 --version ile ^22.23.4 || ^24.22.1 || >=26.12.1 gereksinimini 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?

  1. Benzer sorunlar için GitHub Issues sayfasını kontrol edin
  2. Sorun bildirirken işletim sisteminizi, Node sürümünüzü ve IDE'nizi belirtin
  3. 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).

MetrikAçıklama
circleci.mcp.tool.invocationsAraç çağırma sayısı
circleci.mcp.tool.duration_msMilisaniye cinsinden yürütme süresi
circleci.mcp.tool.errorsHata sayısı

Geliştirme

Başlarken

  1. Depoyu klonlayın:

    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
    cd mcp-server-circleci
    
  2. Bağımlılıkları yükleyin:

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

  1. Geliştirme sunucusunu başlatın:

    pnpm watch # Keep this running in one terminal
    
  2. Ayrı bir terminalde inspector'ı başlatın:

    pnpm inspector
    
  3. Ortamı yapılandırın:

    • CIRCLECI_TOKEN değ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