CircleCI MCP 서버

모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하기 위한 새로운 표준화된 프로토콜 입니다. 이 저장소에서는 CircleCI 용 MCP 서버를 제공합니다.

이를 통해 Cursor IDE, Windsurf, Copilot 또는 MCP 지원 클라이언트를 사용하여 자연어를 사용하여 CircleCI로 작업을 수행할 수 있습니다.예:

• Find the latest failed pipeline on my branch and get logshttps://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

요구 사항

• CircleCI API 토큰 - CircleCI를 통해 생성할 수 있습니다. 자세히 알아보거나 여기를 클릭하여 빠르게 액세스하세요.

NPX 설치의 경우:

• pnpm 패키지 관리자 - 자세히 알아보기

• Node.js >= v18.0.0

Docker 설치의 경우:

• Docker - 자세히 알아보기

Related MCP server: Enhanced Interactive Feedback MCP Server

설치

커서

NPX 사용하기

커서 MCP 구성에 다음을 추가하세요.

지엑스피1

Docker 사용

커서 MCP 구성에 다음을 추가하세요.

VS 코드

NPX 사용하기

.vscode/mcp.json 에 VS Code용 CircleCI MCP 서버를 설치하려면 다음을 수행합니다.

Docker 사용

Docker를 사용하여 .vscode/mcp.json 에 VS Code용 CircleCI MCP 서버를 설치하려면:

클로드 데스크탑

NPX 사용하기

claude_desktop_config.json에 다음을 추가하세요.

Docker 사용

claude_desktop_config.json에 다음을 추가하세요.

이 파일을 찾거나 생성하려면 먼저 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를 설치한 후 다음 명령을 실행하세요.

Docker 사용

Claude Code를 설치한 후 다음 명령을 실행하세요.

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에 다음을 추가하세요.

Docker 사용

windsurf mcp_config.json에 다음을 추가하세요.

Windsurf와 함께 MCP 서버를 사용하는 방법에 대한 자세한 내용은 아래 가이드를 참조하세요: https://docs.windsurf.com/windsurf/mcp

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 CircleCI MCP 서버를 자동으로 설치하려면:

특징

지원되는 도구

• get_build_failure_logs

  CircleCI 빌드에서 자세한 실패 로그를 검색합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.

  1. Project Slug 및 Branch 사용(권장 워크플로):

     • 먼저, 사용 가능한 프로젝트를 나열하세요.

       • list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.

       • 예: "내 CircleCI 프로젝트 나열"

       • 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.

       • 예: "내 프로젝트를 사용해 보자"

     • 그런 다음 특정 브랜치에 대한 빌드 실패 로그를 검색하도록 요청합니다.

       • 예: "메인 브랜치에서 my-project에 대한 빌드 실패를 가져옵니다"

  2. CircleCI URL 사용:

     • 실패한 작업 URL 또는 파이프라인 URL을 직접 제공하세요.

     • 예: " https://app.circleci.com/pipelines/github/org/repo/123 에서 로그 가져오기"

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

     • 다음을 제공하여 로컬 작업 공간에서 작업합니다.

       • 작업 공간 루트 경로

       • Git 원격 URL

       • 지점 이름

     • 예: "현재 분기에서 가장 최근에 실패한 파이프라인 찾기"

  이 도구는 다음을 포함한 형식화된 로그를 반환합니다.

  • 직업 이름

  • 단계별 실행 세부 정보

  • 실패 메시지 및 컨텍스트

  이 기능은 다음과 같은 경우에 특히 유용합니다.

  • 실패한 빌드 디버깅

  • 테스트 실패 분석

  • 배포 문제 조사

  • IDE를 벗어나지 않고도 빌드 로그에 빠르게 액세스

• find_flaky_tests

  테스트 실행 기록을 분석하여 CircleCI 프로젝트에서 불안정한 테스트를 식별합니다. 이 기능은 https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection 에서 설명하는 불안정한 테스트 감지 기능을 활용합니다.

  이 도구는 세 가지 방법으로 사용할 수 있습니다.

  1. Project Slug 사용(권장 워크플로):

     • 먼저, 사용 가능한 프로젝트를 나열하세요.

       • list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.

       • 예: "내 CircleCI 프로젝트 나열"

       • 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.

       • 예: "내 프로젝트를 사용해 보자"

     • 그런 다음 불안정한 테스트를 검색하도록 요청합니다.

       • 예: "내 프로젝트에 대한 불안정한 테스트 가져오기"

  2. CircleCI 프로젝트 URL 사용:

     • CircleCI에서 직접 프로젝트 URL을 제공하세요

     • 예: " https://app.circleci.com/pipelines/github/org/repo 에서 불안정한 테스트 찾기"

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

     • 다음을 제공하여 로컬 작업 공간에서 작업합니다.

       • 작업 공간 루트 경로

       • Git 원격 URL

     • 예: "현재 프로젝트에서 불안정한 테스트 찾기"

  이 도구는 다음을 포함하여 불안정한 테스트에 대한 자세한 정보를 반환합니다.

  • 테스트 이름 및 파일 위치

  • 실패 메시지 및 컨텍스트

  이것은 당신에게 도움이 됩니다:

  • 테스트 모음에서 신뢰할 수 없는 테스트 식별

  • 테스트 실패에 대한 자세한 컨텍스트를 얻으세요

  • 테스트 개선에 대한 데이터 기반 의사 결정

• get_latest_pipeline_status

  지정된 브랜치의 최신 파이프라인 상태를 검색합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.

  1. Project Slug 및 Branch 사용(권장 워크플로):

     • 먼저, 사용 가능한 프로젝트를 나열하세요.

       • list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.

       • 예: "내 CircleCI 프로젝트 나열"

       • 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.

       • 예: "내 프로젝트를 사용해 보자"

     • 그런 다음 특정 분기의 최신 파이프라인 상태를 검색하도록 요청합니다.

       • 예: "메인 브랜치에서 my-project의 최신 파이프라인 상태를 가져옵니다"

  2. CircleCI 프로젝트 URL 사용:

     • CircleCI에서 직접 프로젝트 URL을 제공하세요

     • 예: " https://app.circleci.com/pipelines/github/org/repo 에 대한 최신 파이프라인의 상태를 가져옵니다"

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

     • 다음을 제공하여 로컬 작업 공간에서 작업합니다.

       • 작업 공간 루트 경로

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

  CircleCI 작업에 대한 테스트 메타데이터를 검색하여 IDE를 벗어나지 않고도 테스트 결과를 분석할 수 있도록 합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.

  1. Project Slug 및 Branch 사용(권장 워크플로):

     • 먼저, 사용 가능한 프로젝트를 나열하세요.

       • list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.

       • 예: "내 CircleCI 프로젝트 나열"

       • 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.

       • 예: "내 프로젝트를 사용해 보자"

     • 그런 다음 특정 지점에 대한 테스트 결과를 검색하도록 요청합니다.

       • 예: "메인 브랜치에서 my-project에 대한 테스트 결과 가져오기"

  2. CircleCI URL 사용:

     • 다음 형식 중 하나로 CircleCI URL을 제공하세요.

       • 작업 URL: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 "

       • 워크플로 URL: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "

       • 파이프라인 URL: " https://app.circleci.com/pipelines/github/org/repo/123 "

     • 예: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def 에 대한 테스트 결과 가져오기"

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

     • 다음을 제공하여 로컬 작업 공간에서 작업합니다.

       • 작업 공간 루트 경로

       • Git 원격 URL

       • 지점 이름

     • 예: "메인 브랜치에서 현재 프로젝트에 대한 테스트 결과를 가져옵니다"

  이 도구는 자세한 테스트 결과 정보를 반환합니다.

  • 모든 테스트 요약(전체, 성공, 실패)

  • 실패한 테스트에 대한 자세한 정보:

    • 테스트 이름 및 클래스

    • 파일 위치

    • 오류 메시지

    • 런타임 지속 시간

  • 타이밍 정보가 포함된 성공적인 테스트 목록

  • 테스트 결과로 필터링

  이 기능은 특히 다음과 같은 경우에 유용합니다.

  • CircleCI 웹 UI를 방문하지 않고도 테스트 실패를 빠르게 분석

  • 테스트 실패 패턴 식별

  • 최적화가 필요할 수 있는 느린 테스트 찾기

  • 프로젝트 전체에서 테스트 범위 확인

  • 불안정한 테스트 문제 해결

  참고: 이 도구를 사용하려면 CircleCI 설정에서 테스트 메타데이터가 올바르게 구성되어 있어야 합니다. 테스트 메타데이터 수집 설정에 대한 자세한 내용은 https://circleci.com/docs/collect-test-data/를 참조하세요.

• config_helper

  CircleCI 구성 작업에 대한 지침과 검증을 제공하여 도움을 줍니다. 이 도구는 다음과 같은 작업에 도움이 됩니다.

  1. CircleCI 구성 검증:

     • .circleci/config.yml에서 구문 및 의미 오류를 확인합니다.

     • 예: "CircleCI 구성 검증"

  이 도구는 다음을 제공합니다.

  • 자세한 검증 결과

  • 구성 권장 사항

  이것은 당신에게 도움이 됩니다:

  • 푸시하기 전에 구성 오류를 잡아라

  • CircleCI 구성 모범 사례를 알아보세요

  • 구성 문제 해결

  • CircleCI 기능을 올바르게 구현하세요

• create_prompt_template

  기능 요구 사항을 기반으로 AI 지원 애플리케이션에 대한 체계적인 프롬프트 템플릿을 생성하는 데 도움이 됩니다. 이 도구는 다음을 수행합니다.

  1. 기능 요구 사항을 구조화된 프롬프트로 변환합니다.

     • 사용자 요구 사항을 최적화된 프롬프트 템플릿으로 변환합니다.

     • 예: "연령 및 주제에 따라 취침 시간 이야기를 생성하기 위한 프롬프트 템플릿 만들기"

  이 도구는 다음을 제공합니다.

  • 구조화된 프롬프트 템플릿

  • 필수 입력 매개변수를 정의하는 컨텍스트 스키마

  이것은 당신에게 도움이 됩니다:

  • AI 애플리케이션을 위한 효과적인 프롬프트를 만듭니다.

  • 일관된 결과를 위해 입력 매개변수를 표준화합니다.

  • 강력한 AI 기반 기능 구축

• recommend_prompt_template_tests

  예상 결과가 생성되는지 확인하기 위해 즉각적인 템플릿에 대한 테스트 케이스를 생성합니다. 이 도구는 다음을 수행합니다.

  1. 프롬프트 템플릿에 대한 테스트 케이스를 제공합니다.

     • 프롬프트 템플릿과 컨텍스트 스키마를 기반으로 다양한 테스트 시나리오를 생성합니다.

     • 예: "취침 시간 이야기 프롬프트 템플릿에 대한 테스트 생성"

  이 도구는 다음을 제공합니다.

  • 추천되는 테스트 케이스의 배열

  • 템플릿 견고성을 테스트하기 위한 다양한 매개변수 조합

  이것은 당신에게 도움이 됩니다:

  • 프롬프트 템플릿 기능 검증

  • 입력 전반에 걸쳐 일관된 AI 응답을 보장합니다.

  • 에지 케이스와 잠재적인 문제 식별

  • 전반적인 AI 애플리케이션 품질 개선

• list_followed_projects

  CircleCI에서 사용자가 팔로우하는 모든 프로젝트를 나열합니다. 이 도구는 다음을 수행합니다.

  1. 프로젝트 검색 및 표시:

     • 사용자가 액세스할 수 있고 팔로우하고 있는 모든 프로젝트를 표시합니다.

     • 각 항목에 대한 프로젝트 이름과 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

  파이프라인을 실행합니다. 이 도구는 세 가지 방법으로 사용할 수 있습니다.

  1. Project Slug 및 Branch 사용(권장 워크플로):

     • 먼저, 사용 가능한 프로젝트를 나열하세요.

       • list_followed_projects 도구를 사용하여 프로젝트를 가져옵니다.

       • 예: "내 CircleCI 프로젝트 나열"

       • 그런 다음 프로젝트와 연관된 projectSlug가 있는 프로젝트를 선택하세요.

       • 예: "내 프로젝트를 사용해 보자"

     • 그런 다음 특정 분기에 대한 파이프라인을 실행하도록 요청합니다.

       • 예: "메인 브랜치에서 my-project에 대한 파이프라인을 실행하세요"

  2. CircleCI URL 사용:

     • 다음 형식 중 하나로 CircleCI URL을 제공하세요.

       • 작업 URL: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 "

       • 워크플로 URL: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "

       • 파이프라인 URL: " https://app.circleci.com/pipelines/github/org/repo/123 "

       • 브랜치가 있는 프로젝트 URL: " https://app.circleci.com/projects/github/org/repo?branch=main "

     • 예: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def 에 대한 파이프라인을 실행합니다."

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

     • 다음을 제공하여 로컬 작업 공간에서 작업합니다.

       • 작업 공간 루트 경로

       • Git 원격 URL

       • 지점 이름

     • 예: "메인 브랜치에서 현재 프로젝트의 파이프라인을 실행합니다"

  이 도구는 파이프라인 실행을 모니터링하기 위한 링크를 반환합니다.

  이 기능은 다음과 같은 경우에 특히 유용합니다.

  • CircleCI 웹 UI를 방문하지 않고도 파이프라인을 빠르게 실행합니다.

  • 특정 지점에서 파이프라인 실행

개발

시작하기

1. 저장소를 복제합니다.

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

2. 종속성 설치:

   pnpm install

3. 프로젝트를 빌드하세요:

   pnpm build

Docker 컨테이너 빌드

다음을 사용하여 Docker 컨테이너를 로컬로 빌드할 수 있습니다.

이렇게 하면 MCP 클라이언트에서 사용할 수 있는 circleci:mcp-server-circleci 라는 태그가 지정된 Docker 이미지가 생성됩니다.

컨테이너를 실행하려면:

MCP Inspector를 활용한 개발

MCP 서버에서 반복 작업을 수행하는 가장 쉬운 방법은 MCP 검사기를 사용하는 것입니다. MCP 검사기에 대한 자세한 내용은 https://modelcontextprotocol.io/docs/tools/inspector 에서 확인할 수 있습니다.

1. 개발 서버를 시작합니다.

   pnpm watch # Keep this running in one terminal

2. 별도의 터미널에서 검사기를 실행합니다.

   pnpm inspector

3. 환경 구성:

   • 검사기 UI의 환경 변수 섹션에 CIRCLECI_TOKEN 추가합니다.

   • 토큰에는 CircleCI 프로젝트에 대한 읽기 액세스 권한이 필요합니다.

   • 선택적으로 CircleCI 기본 URL을 설정할 수 있습니다. 기본값은 https//circleci.com 입니다.

테스트

• 테스트 모음을 실행합니다.

  pnpm test

• 개발 중에 감시 모드에서 테스트를 실행합니다.

  pnpm test:watch

더 자세한 기여 지침은 CONTRIBUTING.md를 참조하세요.