Home
Login
CircleCI-Public/mcp-server-circleciPlease refer to the latest official releases for information GitHub Homepage

CircleCI MCP 서버 - 모델 컨텍스트 프로토콜을 위해 특별히 설계된 전문 서버 구현으로, CircleCI 개발 워크플로우 통합에 사용됩니다.

Apache-2.0TypeScript 50CircleCI-Publicmcp-server-circleci Last Updated: 2025-06-23

CircleCI MCP 서버 프로젝트 소개

프로젝트 개요

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

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

핵심 기능

주요 도구 및 기능

1. get_build_failure_logs

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

CircleCI URL 사용:

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

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

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

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

2. find_flaky_tests

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

CircleCI 프로젝트 URL 사용:

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

  • 작업 공간 루트 경로 및 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

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

설치 및 구성

시스템 요구 사항

지원되는 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

개발 및 기여

로컬 개발 설정

  1. 리포지토리 복제:
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci
  1. 종속성 설치:
pnpm install
  1. 프로젝트 빌드:
pnpm build

MCP 검사기를 사용하여 개발

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

  1. 개발 서버 시작:
pnpm watch # 하나의 터미널에서 계속 실행
  1. 별도의 터미널에서 검사기 시작:
pnpm inspector
  1. 환경 구성:
    • 검사기 UI의 환경 변수 섹션에 CIRCLECI_TOKEN을 추가합니다.
    • 토큰에는 CircleCI 프로젝트에 대한 읽기 권한이 필요합니다.
    • 선택적으로 CircleCI 기본 URL을 설정할 수 있습니다. 기본값은 https://circleci.com입니다.

테스트

테스트 스위트 실행:

pnpm test

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

pnpm test:watch

적용 시나리오

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

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

프로젝트 장점

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

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

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

관련 자료

더 자세한 기여 가이드는 프로젝트의 CONTRIBUTING.md 파일을 참조하십시오.

Star History Chart