CircleCI MCP 서버

AI 도구를 위한 CI/CD 컨텍스트

CircleCI MCP 서버는 커서, 클로드 코드, 윈드서프 등 AI 도구가 빌드 시스템을 이해할 수 있게 만들어 줍니다. 이 서버는 Model Context Protocol(MCP) 위에 구축되었는데, MCP는 LLM 기반 에이전트가 외부 시스템으로부터 구조화된 데이터를 가져올 수 있게 해주는 가볍고 표준화된 프로토콜입니다.

CircleCI MCP 서버에 연결함으로써 에이전트는 다음 영역에 대한 실시간 가시성을 얻습니다:

로그 빌드 및 테스트 결과
파이프라인 상태
최근 구성 변경 사항
워크플로우 성과 지표

즉, 작업 기록이나 대시보드 UI를 뒤지는 대신, 다음처럼 물어볼 수 있습니다:

why did my last build fail?

그러면 문제 해결에 필요한 모든 컨텍스트를 즉시 얻어 작업 흐름을 끊지 않고 계속 진행할 수 있습니다.

빌드 데이터를 실행으로 전환

설치 후 MCP 서버는 자연어를 통해 CI/CD 데이터를 접근할 수 있게 합니다. LLM 기반 도구는 다음과 같은 기능을 제공합니다:

빌드 실패 원인 진단
구조화된 오류 요약 및 로그를 제공합니다.

최근 변경 사항으로 실패 추적
회귀 현상을 커밋, 차이점 또는 워크플로와 연결합니다.

불안정한 테스트 발견
테스트 기록에서 불안정성 패턴을 파악합니다.

개선 사항 권장
상황에 맞는 구성 또는 타이밍 최적화를 제안합니다.

CI 데이터를 에디터로 가져오기
탭 전환 없이 LLM 도구를 활용해 빌드 과정을 추론합니다.

코드와 빌드 컨텍스트에 동시에 접근할 수 있기 때문에, 이러한 도구들은 버그를 더 빠르게 수정하고, 변경 사항을 자신 있게 배포하며, 정말 중요한 작업에 집중할 수 있도록 도와줍니다.

Recommended setup

For local editors — use the CircleCI CLI. The MCP server is built directly into the CLI, which is the recommended way to connect Cursor, VS Code, Claude Desktop, and similar tools to CircleCI.

For web-hosted agents like Claude.ai, or if company policy prefers — use the hosted MCP server, which connects via OAuth2 and requires no local install.

Both can be active at the same time.

Note for current standalone MCP server users: Our original standalone MCP server is in maintenance mode and is no longer recommended. If you need to stay on the standalone server for now, use version 0.19.0 or later. Installs that use the @latest tag pick this up automatically; if you pin a specific version, point your configuration at @circleci/mcp-server-circleci@0.19.0.

MCP로 시작하기

CircleCI MCP Server는 로컬에서 실행되며 다양한 편집기 및 LLM 개발 도구와 통합됩니다.

아래에 선호하는 환경에서 MCP Server를 설치하는 데 사용할 수 있는 바로 사용 가능한 구성 예시를 제공합니다.

사전 요구 사항

IDE를 설정하기 전에 다음 사항을 갖추었는지 확인하세요.

CircleCI 개인 API 토큰(PAT):
- 사용자 설정 > 개인 API 토큰 으로 이동합니다
- 새 토큰 만들기 를 클릭합니다
- 복사하여 안전하게 보관하세요 — 설정 중에 CIRCLECI_TOKEN으로 사용합니다
NPX 설치의 경우:
- pnpm 패키지 관리자
- Node.js 버전 ≥ 18.0.0
Docker 설치의 경우:
- Docker

구성 안내

Cursor

NPX 사용:


{
  "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"
      }
    }
  }
}

Docker 사용:


{
  "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"
      }
    }
  }
}

Cursor 설정 문서

VS Code

NPX 사용:


{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API 토큰",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI 기본 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}"
      }
    }
  }
}

Docker 사용:


{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API 토큰",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI 기본 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}"
      }
    }
  }
}

VS Code 설정 문서

Claude Desktop

NPX 사용:


{
  "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"
      }
    }
  }
}

Docker 사용:


{
  "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"
      }
    }
  }
}

구성 파일 위치:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop 설정 문서

Claude Code

NPX 사용:


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

Docker 사용:


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 설정 문서

Windsurf

NPX 사용:


{
  "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"
      }
    }
  }
}

Docker 사용:


{
  "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"
      }
    }
  }
}

Windsurf 설정 문서

Amazon Q Developer / Kiro

사전 요구 사항:

CircleCI 개인 API 토큰
NPX: Node.js >= v18 및 pnpm

구성 파일:
Amazon Q Developer 및 Kiro CLI는 MCP 클라이언트 구성을 JSON 형식으로 저장합니다. 구성 경로는 사용 중인 도구에 따라 다릅니다.

Amazon Q Developer:
- 로컬: .amazonq/agents/default.json
- 전역: ~/.aws/amazonq/agents/default.json

Kiro CLI:
- 워크스페이스: .kiro/settings/mcp.json
- 전역: ~/.kiro/settings/mcp.json

위의 Amazon Q Developer 경로는 기본 에이전트용입니다. 커스텀 에이전트를 사용하는 경우 해당 에이전트의 구성 파일에 MCP Server 구성을 추가하세요.

둘 다 선택 사항입니다. 둘 다 존재하는 경우 두 구성 모두에서 읽습니다. 동일한 서버가 둘 다에 정의된 경우 로컬/워크스페이스 구성이 사용됩니다.

NPX 사용(로컬 MCP Server):

구성 파일에 다음을 추가하세요:

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // 선택 사항. 온프레미스 환경에서만 필요
      },
      "timeout": 60000
    }
  }
}

자체 관리 원격 MCP Server 사용:

래퍼 스크립트를 생성합니다(예: circleci-remote-mcp.sh):

#!/bin/bash
export CIRCLECI_TOKEN="your-circleci-token"
npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

실행 가능하게 설정합니다:

chmod +x circleci-remote-mcp.sh

원격 서버 추가:

Kiro CLI를 통해:

kiro-cli mcp add --name circleci --command "/full/path/to/circleci-remote-mcp.sh"

Amazon Q MCP 구성 UI를 통해:

전역 또는 로컬 범위를 선택합니다
서버 이름을 입력합니다(예: circleci-remote-mcp)
전송 프로토콜을 설정합니다: stdio
명령을 설정합니다: 래퍼 스크립트 경로(예: /full/path/to/circleci-remote-mcp.sh)
구성을 저장합니다

Smithery로 설치


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

사용 가능한 도구

AI 기반 개발 가속화부터 에이전트 워크플로 오케스트레이션까지, MCP Server가 제공하는 각 도구는 AI 개발자에게 구조화된 CI/CD 컨텍스트를 제공하여 더 빠르고 안정적인 릴리스 사이클을 실현합니다.

도구	용도
`config_helper`	파이프라인에 영향을 주기 전에 구성 문제 수정
`create_prompt_template`	일관된 AI 동작을 지원하는 프롬프트 템플릿 생성
`find_flaky_tests`	불안정한 테스트 식별 및 문제 해결
`get_build_failure_logs`	빌드 실패를 더 빠르게 디버그하고 해결
`get_job_test_results`	테스트 실패 및 성능 문제 분석 및 해결
`get_latest_pipeline_status`	파이프라인 상태 모니터링 및 대응
`list_followed_projects`	팔로우 중인 프로젝트 및 해당 `projectSlug` 확인
`recommend_prompt_template_tests`	프롬프트 신뢰성 테스트 및 개선
`rerun_workflow`	처음부터 또는 실패한 작업부터 워크플로 재실행
`run_pipeline`	편집기에서 바로 빌드 트리거
`run_rollback_pipeline`	단일 명령으로 결함 있는 배포 롤백

자세히 알아보기

CircleCI MCP Server를 시작하거나, 예시를 살펴보거나, 플랫폼 업데이트 소식을 확인하세요:

프로젝트 저장소 – 소스 코드, 이슈 및 기여 가이드.
MCP Cookbook – 프롬프트 예시와 도구 사용 패턴.
블로그 게시물: CircleCI MCP Server 소개 – 설계 배경 및 활용 사례.
CircleCI 변경 로그 – 최신 플랫폼 업데이트 및 기능 출시 내역 확인.

개요

기능

통합

역할

사용 사례

회사 규모

개발자

탐색

변경 로그

이점

비교

회사

개요

기능

통합

역할

사용 사례

회사 규모

개발자

탐색

변경 로그

이점

비교

회사

CircleCI MCP 서버

AI 도구를 위한 CI/CD 컨텍스트

빌드 데이터를 실행으로 전환

Recommended setup

MCP로 시작하기

사전 요구 사항

구성 안내

사용 가능한 도구

자세히 알아보기