CircleCI MCP 서버 프로젝트 소개

프로젝트 개요

CircleCI MCP 서버는 모델 컨텍스트 프로토콜(MCP)을 위해 특별히 설계된 전문 서버 구현체로, CircleCI의 개발 워크플로우를 통합하는 것을 목표로 합니다. 이 프로젝트는 CircleCI 인프라와 모델 컨텍스트 프로토콜 간의 다리 역할을 하며, 향상된 AI 기반 개발 경험을 제공합니다.

이 서버를 통해 Cursor, Claude Code, Windsurf와 같은 AI 도구가 사용자의 빌드 시스템을 이해할 수 있습니다. 이는 LLM 기반 에이전트가 외부 시스템에서 구조화된 데이터를 가져올 수 있도록 하는 경량 표준인 모델 컨텍스트 프로토콜(MCP)을 기반으로 구축되었습니다.

핵심 기능

주요 도구 및 기능

1. get_build_failure_logs

CircleCI 빌드의 상세 실패 로그를 검색합니다. 이 도구는 두 가지 사용 방식을 지원합니다.

CircleCI URL 사용:

실패한 작업 URL 또는 파이프라인 URL을 직접 제공합니다.
예시: "https://app.circleci.com/pipelines/github/org/repo/123 의 로그 가져오기"

로컬 프로젝트 컨텍스트 사용:

다음 정보를 제공하여 로컬 작업 공간에서 작업합니다.
- 작업 공간 루트 경로
- Git 원격 URL
- 브랜치 이름
예시: "현재 브랜치에서 가장 최근에 실패한 파이프라인 찾기"

반환되는 형식화된 로그는 다음을 포함합니다.

작업 이름
단계별 실행 상세 정보
실패 메시지 및 컨텍스트

2. find_flaky_tests

테스트 실행 기록을 분석하여 CircleCI 프로젝트에서 불안정한 테스트를 식별합니다. 두 가지 사용 방식을 지원합니다.

CircleCI 프로젝트 URL 사용:

CircleCI에서 프로젝트 URL을 직접 제공합니다.
예시: "https://app.circleci.com/pipelines/github/org/repo 에서 불안정한 테스트 찾기"

로컬 프로젝트 컨텍스트 사용:

작업 공간 루트 경로 및 Git 원격 URL을 제공하여 로컬 작업 공간에서 작업합니다.

반환되는 불안정한 테스트의 상세 정보는 다음을 포함합니다.

테스트 이름 및 파일 위치
실패 메시지 및 컨텍스트

3. get_latest_pipeline_status

지정된 브랜치의 최신 파이프라인 상태를 검색합니다. 이 도구는 최신 파이프라인의 형식화된 상태를 반환합니다.

워크플로우 이름 및 현재 상태
각 워크플로우의 지속 시간
생성 및 완료 타임스탬프
전체 파이프라인 상태

예시 출력:

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

4. get_job_test_results

CircleCI 작업의 테스트 메타데이터를 검색하여 IDE를 벗어나지 않고도 테스트 결과를 분석할 수 있습니다.

반환되는 상세 테스트 결과 정보는 다음을 포함합니다.

모든 테스트 요약 (총 개수, 성공, 실패)
실패한 테스트의 상세 정보:
- 테스트 이름 및 클래스
- 파일 위치
- 오류 메시지
- 런타임 지속 시간
시간 정보가 포함된 성공한 테스트 목록

5. config_helper

CircleCI 구성 작업을 지원하고, 지침 및 유효성 검사를 제공합니다. 이 도구는 다음을 지원합니다.

CircleCI 구성 유효성 검사:
- .circleci/config.yml에 구문 및 의미 오류가 있는지 확인합니다.
- 예시: "내 CircleCI 구성 유효성 검사"

제공되는 정보:

상세 유효성 검사 결과
구성 제안

6. create_prompt_template

AI 지원 애플리케이션에 사용할 기능 요구 사항 기반의 구조화된 프롬프트 템플릿을 생성합니다. 이 도구는 다음을 수행합니다.

기능 요구 사항을 구조화된 프롬프트로 변환:
- 사용자 요구 사항을 최적화된 프롬프트 템플릿으로 변환합니다.
- 예시: "나이와 주제별로 잠자리 이야기를 생성하기 위한 프롬프트 템플릿 만들기"

7. recommend_prompt_template_tests

프롬프트 템플릿에 대한 테스트 케이스를 생성하여 예상 결과를 생성하는지 확인합니다.

설치 및 구성

시스템 요구 사항

pnpm 패키지 관리자 - 자세히 알아보기
Node.js >= v18.0.0
CircleCI API 토큰 - CircleCI를 통해 생성할 수 있습니다. 자세히 알아보기 또는 여기를 클릭하여 빠르게 액세스

지원되는 IDE 및 도구

Cursor IDE

다음 내용을 Cursor MCP 구성에 추가합니다.

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // 선택 사항 - 로컬 배포 고객만 해당
      }
    }
  }
}

VS Code

.vscode/mcp.json에 CircleCI MCP 서버를 설치합니다.

{
  // 💡 입력은 첫 번째 서버 시작 시 프롬프트되고 VS Code에서 안전하게 저장됩니다.
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

Claude Desktop

다음 내용을 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" // 선택 사항 - 로컬 배포 고객만 해당
      }
    }
  }
}

구성 파일 위치:

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

Claude Code

Claude Code를 설치한 후 다음 명령을 실행합니다.

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

Windsurf

다음 내용을 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" // 선택 사항 - 로컬 배포 고객만 해당
      }
    }
  }
}

자동 설치

Smithery를 통해 Claude Desktop에 CircleCI MCP 서버를 자동으로 설치합니다.

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

개발 및 기여

로컬 개발 설정

리포지토리 복제:

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

종속성 설치:

pnpm install

프로젝트 빌드:

pnpm build

MCP 검사기를 사용하여 개발

MCP 서버를 반복하는 가장 쉬운 방법은 MCP 검사기를 사용하는 것입니다.

개발 서버 시작:

pnpm watch # 하나의 터미널에서 계속 실행

별도의 터미널에서 검사기 시작:

pnpm inspector

환경 구성:
- 검사기 UI의 환경 변수 섹션에 CIRCLECI_TOKEN을 추가합니다.
- 토큰에는 CircleCI 프로젝트에 대한 읽기 권한이 필요합니다.
- 선택적으로 CircleCI 기본 URL을 설정할 수 있습니다. 기본값은 https://circleci.com입니다.

테스트

테스트 스위트 실행:

pnpm test

개발 중에 감시 모드로 테스트 실행:

pnpm test:watch

적용 시나리오

이 도구는 특히 다음 경우에 유용합니다.

실패한 빌드 디버깅
테스트 실패 분석
배포 문제 조사
IDE를 벗어나지 않고 빌드 로그에 빠르게 액세스
최신 파이프라인 상태 확인
테스트 스위트에서 신뢰할 수 없는 테스트 식별
데이터 기반 의사 결정을 통해 테스트 개선

프로젝트 장점

CircleCI MCP 서버는 개발 수명 주기에서 실제 순간을 지원하도록 설계되었습니다. 실패한 빌드를 검토하든, 실패한 배포를 디버깅하든, 중요한 브랜치에 집중하든, 몇 초 안에 실패를 이해하고 수정 사항을 제안하도록 지원하여 컨텍스트 전환이 필요 없습니다.

이 MCP 서버를 통합함으로써 개발자는 다음을 수행할 수 있습니다.

자연어를 사용하여 CircleCI와 상호 작용
익숙한 개발 환경에서 빌드 정보 가져오기
CI/CD 문제 신속하게 진단 및 해결
개발 워크플로우 효율성 향상

mcp-server-circleci