CircleCI MCP 서버
모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하기 위한 새로운 표준화된 프로토콜 입니다. 이 저장소에서는 CircleCI 용 MCP 서버를 제공합니다.
이를 통해 Cursor IDE, Windsurf, Copilot 또는 MCP 지원 클라이언트를 사용하여 자연어를 사용하여 CircleCI로 작업을 수행할 수 있습니다.예:
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
요구 사항
NPX 설치의 경우:
- pnpm 패키지 관리자 - 자세히 알아보기
- Node.js >= v18.0.0
Docker 설치의 경우:
설치
커서
NPX 사용하기
커서 MCP 구성에 다음을 추가하세요.
지엑스피1
Docker 사용
커서 MCP 구성에 다음을 추가하세요.
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
VS 코드
NPX 사용하기
.vscode/mcp.json 에 VS Code용 CircleCI MCP 서버를 설치하려면 다음을 수행합니다.
{
// 💡 Inputs are prompted on first server start, then stored securely by VS Code.
"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": {
// https://github.com/ppl-ai/modelcontextprotocol/
"circleci-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "${input:circleci-token}",
"CIRCLECI_BASE_URL": "${input:circleci-base-url}"
}
}
}
}
Docker 사용
Docker를 사용하여 .vscode/mcp.json 에 VS Code용 CircleCI MCP 서버를 설치하려면:
{
// 💡 Inputs are prompted on first server start, then stored securely by VS Code.
"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": {
// https://github.com/ppl-ai/modelcontextprotocol/
"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}"
}
}
}
}
클로드 데스크탑
NPX 사용하기
claude_desktop_config.json에 다음을 추가하세요.
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Docker 사용
claude_desktop_config.json에 다음을 추가하세요.
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
이 파일을 찾거나 생성하려면 먼저 Claude 데스크톱 설정을 엽니다. 그런 다음 설정 창 왼쪽 막대에서 "개발자"를 클릭하고 "구성 편집"을 클릭합니다.
이렇게 하면 다음 위치에 구성 파일이 생성됩니다.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Claude Desktop과 함께 MCP 서버를 사용하는 방법에 대한 자세한 내용은 아래 가이드를 참조하세요: https://modelcontextprotocol.io/quickstart/user
클로드 코드
NPX 사용하기
Claude Code를 설치한 후 다음 명령을 실행하세요.
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci
Docker 사용
Claude Code를 설치한 후 다음 명령을 실행하세요.
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
Claude Code와 함께 MCP 서버를 사용하는 방법에 대한 자세한 내용은 아래 가이드를 참조하세요. https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
윈드서핑
NPX 사용하기
windsurf mcp_config.json에 다음을 추가하세요.
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Docker 사용
windsurf mcp_config.json에 다음을 추가하세요.
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Windsurf와 함께 MCP 서버를 사용하는 방법에 대한 자세한 내용은 아래 가이드를 참조하세요: https://docs.windsurf.com/windsurf/mcp
Smithery를 통해 설치
Smithery를 통해 Claude Desktop에 CircleCI MCP 서버를 자동으로 설치하려면:
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
특징
지원되는 도구
get_build_failure_logsCircleCI 빌드에서 자세한 실패 로그를 검색합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.- Project Slug 및 Branch 사용(권장 워크플로):
- 먼저, 사용 가능한 프로젝트를 나열하세요.
- list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.
- 예: "내 CircleCI 프로젝트 나열"
- 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.
- 예: "내 프로젝트를 사용해 보자"
- 그런 다음 특정 브랜치에 대한 빌드 실패 로그를 검색하도록 요청합니다.
- 예: "메인 브랜치에서 my-project에 대한 빌드 실패를 가져옵니다"
- CircleCI URL 사용:
- 로컬 프로젝트 컨텍스트 사용:
- 다음을 제공하여 로컬 작업 공간에서 작업합니다.
- 작업 공간 루트 경로
- Git 원격 URL
- 지점 이름
- 예: "현재 분기에서 가장 최근에 실패한 파이프라인 찾기"
이 도구는 다음을 포함한 형식화된 로그를 반환합니다.
- 직업 이름
- 단계별 실행 세부 정보
- 실패 메시지 및 컨텍스트
이 기능은 다음과 같은 경우에 특히 유용합니다.
- 실패한 빌드 디버깅
- 테스트 실패 분석
- 배포 문제 조사
- IDE를 벗어나지 않고도 빌드 로그에 빠르게 액세스
find_flaky_tests테스트 실행 기록을 분석하여 CircleCI 프로젝트에서 불안정한 테스트를 식별합니다. 이 기능은 https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection 에서 설명하는 불안정한 테스트 감지 기능을 활용합니다.이 도구는 세 가지 방법으로 사용할 수 있습니다.- Project Slug 사용(권장 워크플로):
- 먼저, 사용 가능한 프로젝트를 나열하세요.
- list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.
- 예: "내 CircleCI 프로젝트 나열"
- 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.
- 예: "내 프로젝트를 사용해 보자"
- 그런 다음 불안정한 테스트를 검색하도록 요청합니다.
- 예: "내 프로젝트에 대한 불안정한 테스트 가져오기"
- CircleCI 프로젝트 URL 사용:
- 로컬 프로젝트 컨텍스트 사용:
- 다음을 제공하여 로컬 작업 공간에서 작업합니다.
- 예: "현재 프로젝트에서 불안정한 테스트 찾기"
이 도구는 다음을 포함하여 불안정한 테스트에 대한 자세한 정보를 반환합니다.
- 테스트 이름 및 파일 위치
- 실패 메시지 및 컨텍스트
이것은 당신에게 도움이 됩니다:
- 테스트 모음에서 신뢰할 수 없는 테스트 식별
- 테스트 실패에 대한 자세한 컨텍스트를 얻으세요
- 테스트 개선에 대한 데이터 기반 의사 결정
get_latest_pipeline_status지정된 브랜치의 최신 파이프라인 상태를 검색합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.- Project Slug 및 Branch 사용(권장 워크플로):
- 먼저, 사용 가능한 프로젝트를 나열하세요.
- list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.
- 예: "내 CircleCI 프로젝트 나열"
- 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.
- 예: "내 프로젝트를 사용해 보자"
- 그런 다음 특정 분기의 최신 파이프라인 상태를 검색하도록 요청합니다.
- 예: "메인 브랜치에서 my-project의 최신 파이프라인 상태를 가져옵니다"
- CircleCI 프로젝트 URL 사용:
- 로컬 프로젝트 컨텍스트 사용:
- 다음을 제공하여 로컬 작업 공간에서 작업합니다.
- 작업 공간 루트 경로
- Git 원격 URL
- 지점 이름
- 예: "현재 프로젝트의 최신 파이프라인 상태 가져오기"
이 도구는 최신 파이프라인의 형식화된 상태를 반환합니다.
- 워크플로 이름 및 현재 상태
- 각 워크플로의 기간
- 생성 및 완료 타임스탬프
- 전반적인 파이프라인 상태
출력 예:
---
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
이 기능은 특히 다음과 같은 경우에 유용합니다.
- 최신 파이프라인 상태 확인
- 특정 지점의 최신 파이프라인 상태 가져오기
- IDE를 벗어나지 않고도 최신 파이프라인의 상태를 빠르게 확인하세요
get_job_test_resultsCircleCI 작업에 대한 테스트 메타데이터를 검색하여 IDE를 벗어나지 않고도 테스트 결과를 분석할 수 있도록 합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.- Project Slug 및 Branch 사용(권장 워크플로):
- 먼저, 사용 가능한 프로젝트를 나열하세요.
- list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.
- 예: "내 CircleCI 프로젝트 나열"
- 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.
- 예: "내 프로젝트를 사용해 보자"
- 그런 다음 특정 지점에 대한 테스트 결과를 검색하도록 요청합니다.
- 예: "메인 브랜치에서 my-project에 대한 테스트 결과 가져오기"
- CircleCI URL 사용:
- 로컬 프로젝트 컨텍스트 사용:
- 다음을 제공하여 로컬 작업 공간에서 작업합니다.
- 작업 공간 루트 경로
- Git 원격 URL
- 지점 이름
- 예: "메인 브랜치에서 현재 프로젝트에 대한 테스트 결과를 가져옵니다"
이 도구는 자세한 테스트 결과 정보를 반환합니다.
- 모든 테스트 요약(전체, 성공, 실패)
- 실패한 테스트에 대한 자세한 정보:
- 테스트 이름 및 클래스
- 파일 위치
- 오류 메시지
- 런타임 지속 시간
- 타이밍 정보가 포함된 성공적인 테스트 목록
- 테스트 결과로 필터링
이 기능은 특히 다음과 같은 경우에 유용합니다.
- CircleCI 웹 UI를 방문하지 않고도 테스트 실패를 빠르게 분석
- 테스트 실패 패턴 식별
- 최적화가 필요할 수 있는 느린 테스트 찾기
- 프로젝트 전체에서 테스트 범위 확인
- 불안정한 테스트 문제 해결
참고: 이 도구를 사용하려면 CircleCI 설정에서 테스트 메타데이터가 올바르게 구성되어 있어야 합니다. 테스트 메타데이터 수집 설정에 대한 자세한 내용은 https://circleci.com/docs/collect-test-data/를 참조하세요.
config_helperCircleCI 구성 작업에 대한 지침과 검증을 제공하여 도움을 줍니다. 이 도구는 다음과 같은 작업에 도움이 됩니다.- CircleCI 구성 검증:
- .circleci/config.yml에서 구문 및 의미 오류를 확인합니다.
- 예: "CircleCI 구성 검증"
이 도구는 다음을 제공합니다.
이것은 당신에게 도움이 됩니다:
- 푸시하기 전에 구성 오류를 잡아라
- CircleCI 구성 모범 사례를 알아보세요
- 구성 문제 해결
- CircleCI 기능을 올바르게 구현하세요
create_prompt_template기능 요구 사항을 기반으로 AI 지원 애플리케이션에 대한 체계적인 프롬프트 템플릿을 생성하는 데 도움이 됩니다. 이 도구는 다음을 수행합니다.- 기능 요구 사항을 구조화된 프롬프트로 변환합니다.
- 사용자 요구 사항을 최적화된 프롬프트 템플릿으로 변환합니다.
- 예: "연령 및 주제에 따라 취침 시간 이야기를 생성하기 위한 프롬프트 템플릿 만들기"
이 도구는 다음을 제공합니다.
- 구조화된 프롬프트 템플릿
- 필수 입력 매개변수를 정의하는 컨텍스트 스키마
이것은 당신에게 도움이 됩니다:
- AI 애플리케이션을 위한 효과적인 프롬프트를 만듭니다.
- 일관된 결과를 위해 입력 매개변수를 표준화합니다.
- 강력한 AI 기반 기능 구축
recommend_prompt_template_tests예상 결과가 생성되는지 확인하기 위해 즉각적인 템플릿에 대한 테스트 케이스를 생성합니다. 이 도구는 다음을 수행합니다.- 프롬프트 템플릿에 대한 테스트 케이스를 제공합니다.
- 프롬프트 템플릿과 컨텍스트 스키마를 기반으로 다양한 테스트 시나리오를 생성합니다.
- 예: "취침 시간 이야기 프롬프트 템플릿에 대한 테스트 생성"
이 도구는 다음을 제공합니다.
- 추천되는 테스트 케이스의 배열
- 템플릿 견고성을 테스트하기 위한 다양한 매개변수 조합
이것은 당신에게 도움이 됩니다:
- 프롬프트 템플릿 기능 검증
- 입력 전반에 걸쳐 일관된 AI 응답을 보장합니다.
- 에지 케이스와 잠재적인 문제 식별
- 전반적인 AI 애플리케이션 품질 개선
list_followed_projectsCircleCI에서 사용자가 팔로우하는 모든 프로젝트를 나열합니다. 이 도구는 다음을 수행합니다.- 프로젝트 검색 및 표시:
- 사용자가 액세스할 수 있고 팔로우하고 있는 모든 프로젝트를 표시합니다.
- 각 항목에 대한 프로젝트 이름과 projectSlug를 제공합니다.
- 예: "내 CircleCI 프로젝트 나열"
이 도구는 프로젝트의 형식화된 목록을 반환합니다. 출력 예는 다음과 같습니다.
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)
이 기능은 특히 다음과 같은 경우에 유용합니다.
- 귀하가 사용할 수 있는 CircleCI 프로젝트 식별
- 다른 CircleCI 도구에 필요한 projectSlug 얻기
- 후속 작업을 위한 프로젝트 선택
참고: projectSlug(프로젝트 이름이 아님)는 다른 여러 CircleCI 도구에 필요하며, 프로젝트를 선택한 후 해당 도구 호출에 사용됩니다.
run_pipeline파이프라인을 실행합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.- Project Slug 및 Branch 사용(권장 워크플로):
- 먼저, 사용 가능한 프로젝트를 나열하세요.
- list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.
- 예: "내 CircleCI 프로젝트 나열"
- 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.
- 예: "내 프로젝트를 사용해 보자"
- 그런 다음 특정 분기에 대한 파이프라인을 실행하도록 요청합니다.
- 예: "메인 브랜치에서 my-project에 대한 파이프라인을 실행하세요"
- CircleCI URL 사용:
- 로컬 프로젝트 컨텍스트 사용:
- 다음을 제공하여 로컬 작업 공간에서 작업합니다.
- 작업 공간 루트 경로
- Git 원격 URL
- 지점 이름
- 예: "메인 브랜치에서 현재 프로젝트의 파이프라인을 실행합니다"
이 도구는 파이프라인 실행을 모니터링하기 위한 링크를 반환합니다.
이 기능은 다음과 같은 경우에 특히 유용합니다.
- CircleCI 웹 UI를 방문하지 않고도 파이프라인을 빠르게 실행합니다.
- 특정 지점에서 파이프라인 실행
개발
시작하기
- 저장소를 복제합니다.
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci
- 종속성 설치:
- 프로젝트를 빌드하세요:
Docker 컨테이너 빌드
다음을 사용하여 Docker 컨테이너를 로컬로 빌드할 수 있습니다.
docker build -t circleci:mcp-server-circleci .
이렇게 하면 MCP 클라이언트에서 사용할 수 있는 circleci:mcp-server-circleci 라는 태그가 지정된 Docker 이미지가 생성됩니다.
컨테이너를 실행하려면:
docker run --rm -i -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com circleci:mcp-server-circleci
MCP Inspector를 활용한 개발
MCP 서버에서 반복 작업을 수행하는 가장 쉬운 방법은 MCP 검사기를 사용하는 것입니다. MCP 검사기에 대한 자세한 내용은 https://modelcontextprotocol.io/docs/tools/inspector 에서 확인할 수 있습니다.
- 개발 서버를 시작합니다.
pnpm watch # Keep this running in one terminal
- 별도의 터미널에서 검사기를 실행합니다.
- 환경 구성:
- 검사기 UI의 환경 변수 섹션에
CIRCLECI_TOKEN 추가합니다. - 토큰에는 CircleCI 프로젝트에 대한 읽기 액세스 권한이 필요합니다.
- 선택적으로 CircleCI 기본 URL을 설정할 수 있습니다. 기본값은
https//circleci.com 입니다.
테스트
- 테스트 모음을 실행합니다.
- 개발 중에 감시 모드에서 테스트를 실행합니다.
더 자세한 기여 지침은 CONTRIBUTING.md를 참조하세요.