TeamCity MCP 서버
CI
CodeQL
codecov
License: MIT
모델 제어 프로토콜(Model Control Protocol, MCP) 서버로, AI 코딩 어시스턴트와 JetBrains TeamCity CI/CD 서버를 연결하며, TeamCity 작업을 MCP 도구로 노출합니다.
<a href="https://glama.ai/mcp/servers/@Daghis/teamcity-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@Daghis/teamcity-mcp/badge" alt="TeamCity Server MCP server" />
</a>
[!NOTE]
프로젝트 상태 (2026년 10월): 안정적이며, 낮은 수준의 유지보수 단계입니다. 이 프로젝트는 본래 목적을 수행하며 더 이상 활발한 개발 중이 아닙니다. 여전히 작동하고 설치 가능하지만, 이슈 및 PR에 대한 응답은 느리거나 없을 수 있으며 보안 수정은 최선을 다하는 수준으로 이루어집니다.
JetBrains가 TeamCity용 공식 AI 통합 기능을 제공합니다 — 이는 TeamCity 2026.1+ 및 TeamCity CLI에 내장된 MCP 서버이자 설치 가능한 에이전트 스킬을 통해 구현되었으며, 대부분의 워크플로우에서 더 나은 기본 옵션입니다. 채택하기 전에 아래 How this compares to JetBrains' official tooling를 참조하십시오.
개요 (Overview)
TeamCity MCP 서버는 AI 기반 코딩 어시스턴트(Claude Code, Cursor, Windsurf)를 사용하는 개발자가 MCP 도구를 통해 개발 환경에서 TeamCity와 직접 상호 작용할 수 있도록 합니다.
1.x 버전에서 업그레이드하나요? 버전 2.0.0에서는 큐 관리, 에이전트 호환성 검사, 서버 상태 모니터링을 포함하여 15개의 도구가 Dev 모드에서 Full 모드로 이동했습니다. 만약 개발 모드(Dev mode)에서 이 도구들에 의존했다면, MCP_MODE=full로 전환하거나 런타임 모드 스위칭(v2.1.0 이상)을 사용하십시오. 자세한 내용은 CHANGELOG.md를 참조하십시오.
기능 (Features)
🚀 운영 모드 2가지
-
개발 모드 (Dev Mode) (기본값): 안전한 CI/CD 작업 수행 가능 (31개 도구, 약 14k 컨텍스트 토큰)
- 빌드를 트리거하고 상태를 모니터링합니다.
- 빌드 로그를 가져오고 테스트 실패를 검사합니다.
- 프로젝트, 구성(configuration), 및 대기열 목록을 확인합니다.
- 매개변수를 읽고 문제를 조사합니다.
-
전체 모드 (Full Mode): 완전한 인프라 관리 기능 제공 (87개 도구, 약 26k 컨텍스트 토큰)
- 모든 개발 모드 기능을 포함하며, 다음을 추가로 지원합니다:
- 빌드 구성을 생성 및 복제합니다.
- 빌드 단계(build steps), 트리거, 종속성(dependencies)을 관리합니다.
- VCS(버전 관리 시스템) 루트와 에이전트를 구성합니다.
- 매개변수에 대한 전체 CRUD (빌드 구성, 프로젝트, 출력 매개변수)를 지원합니다.
- 대기열 관리 및 서버 관리를 수행합니다.
런타임 모드 전환 (Runtime Mode Switching) (v2.1.0 이상): get_mcp_mode와 set_mcp_mode 도구를 사용하여 런타임에 모드를 전환할 수 있으며, 재시작이 필요 없습니다. 알림을 지원하는 MCP 클라이언트는 도구 목록이 자동으로 업데이트되는 것을 확인할 수 있습니다.
87개 도구 전체 목록과 각 모드별 가용성은 도구 모드 매트릭스(Tools Mode Matrix)를 참조하십시오.
🎯 주요 기능 (Key Capabilities)
- 빌드를 트리거하고 모니터링하며, 로그를 가져오고 테스트 실패를 검사합니다.
- TeamCity에 대한 토큰 기반 인증을 사용하며, 민감한 값은 로그에서 마스킹 처리됩니다.
- 현대적인 아키텍처: 싱글턴 클라이언트를 이용한 간단하고 직접적인 구현입니다.
- 성능 지향적: 최소한의 오버헤드로 빠른 시작 속도를 제공합니다.
- 명확한 모듈 경계를 가진 깔끔한 코드베이스를 갖추고 있습니다.
JetBrains의 공식 도구와 비교
2026년 10월 기준 (TeamCity 2026.2, TeamCity CLI 1.6), JetBrains는 AI 에이전트를 위한 두 가지 퍼스트 파티 경로를 제공하며, 이들은 모두 일반적으로 사용 가능하고 공식적으로 지원됩니다.
- 내장 MCP 서버(Built-in MCP server) — 모든 TeamCity 2026.1 이상 서버(클라우드 및 온프레미스)는
<server-url>/app/mcp에서 MCP 엔드포인트를 노출하므로 설치할 것이 없습니다. 이 도구 세트는 의도적으로 작게 설계되었습니다: 빌드 로그, 일반적인 REST API의 GET/POST 패스스루 도구, 그리고 (2026.2 이후) 파이프라인 도구들입니다. 기본적으로 에이전트가 개인 빌드를 읽고 큐에 넣을 수 있는 안전 모드(safe mode)로 실행됩니다. 선택적 '브레이브 모드'(brave mode)를 사용하면 임의의 REST POST 요청을 보내고 파이프라인을 편집하거나 삭제할 수 있습니다. 또한 2026.2 이후부터는 액세스 토큰을 붙여넣는 대신 OAuth를 사용하여 로그인할 수도 있습니다.
- TeamCity CLI — 오픈 소스
teamcity 명령어(TeamCity 2020.1 이상)이며, Claude Code, Cursor 및 기타 에이전트를 위한 설치 가능한 에이전트 스킬(teamcity skill install)을 제공합니다. 이 명령어는 실행(runs), 로그, 테스트, 큐, 에이전트, 풀(pools), 프로젝트, VCS 루트, 매개변수 및 파이프라인을 다루며, teamcity api를 통해 원시 REST 액세스로 폴백하고 읽기 전용 모드(TEAMCITY_RO=1)를 가지고 있습니다. JetBrains 자체 문서는 이를 두 옵션 중 더 광범위하다고 설명합니다.
teamcity-mcp는 해당 도구보다 먼저 존재했으며, 이와 크게 겹칩니다. 오늘날 공식 도구가 더 나은 기본 옵션입니다. teamcity-mcp가 여전히 제공하는 것은 이전보다 범위가 좁습니다:
- 2026.1보다 오래된 서버용 MCP 서버. 클라이언트가 MCP만 지원하고 팀시티 서버가 내장 엔드포인트보다 이전 버전인 경우에도 여전히 작동합니다(TeamCity 2020.1 이상).
- REST 패스스루 대신 목적에 맞게 구축된 MCP 도구. 이 도구는 87개의 타입이 지정된 도구를 노출하며(Dev/Full 모드에 의해 제한됨), 에이전트가 REST 경로와 로케이터를 알 필요가 없습니다. 또한 내장 MCP의 일반적인
GET/POST 도구가 접근하지 못하는, 에이전트 활성화 또는 매개변수 삭제와 같은 PUT/DELETE로 지원되는 작업을 다룹니다.
JetBrains의 도구는 빠르게 발전하고 있으므로(여기서 기능별 비교를 확정하는 것보다) 현재 문서를 확인하고 자신에게 맞는 것을 선택하십시오:
JetBrains의 CLI(Command Line Interface) 사용에 익숙하다면, 이 프로젝트가 전혀 필요하지 않을 수도 있습니다. 이 프로젝트는 MIT 라이선스를 유지하며, 내장 기능이 아직 도달하지 못한 모든 것을 위해 설치 가능합니다. 직접 더 발전시키고 싶다면 포크(fork)하세요.
설치 (Installation)
전제 조건 (Prerequisites)
- Node.js >= 20.10.0 (LTS 버전 20, 22, 24는 CI에서 테스트됨)
- REST API 접근이 가능한 TeamCity Server 2020.1 이상
- TeamCity 인증 토큰
빠른 시작 (Quick Start)
git clone https://github.com/Daghis/teamcity-mcp.git
cd teamcity-mcp
...
npm 패키지 (npm Package)
npx를 통해 MCP 서버를 실행합니다 (Node 20.x 필요). 환경 변수는 인라인으로 설정하거나 작업 디렉터리의 .env 파일을 통해 설정하세요.
TEAMCITY_URL="https://teamcity.example.com" \
TEAMCITY_TOKEN="<your_token>" \
...
Claude 코드
- MCP 추가하기 (.env를 이용한 설정 방식):
claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
- 환경 변수 사용 시 (만약 .env를 사용하지 않는 경우):
claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp
- CLI 인자 사용 시 (Windows에 권장됨):
claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev
- 프로젝트 범위(기본값)가 아닌 사용자 전체 범위에 설치하려면
-s user를 추가하세요.
- 컨텍스트 사용량 (Opus 4.1, 추정치):
- Dev (기본값): MCP 도구용 약 14k 토큰
- Full (
MCP_MODE=full): MCP 도구용 약 26k 토큰
Windows 사용자
Windows에서는 Claude Code의 MCP 설정이 환경 변수를 제대로 병합하지 못할 수 있습니다. 따라서 CLI 인자를 우회 방법으로 사용하세요:
{
"mcpServers": {
"teamcity": {
...
또는 보안을 위해 설정 파일(토큰이 프로세스 목록에 노출되지 않음)을 사용하는 것이 좋습니다:
{
"mcpServers": {
"teamcity": {
...
설정 (Configuration)
환경 변수는 Zod를 통해 중앙에서 검증됩니다. 지원되는 변수와 기본값은 다음과 같습니다:
# 서버 설정
PORT=3000
NODE_ENV=development
...
이 값들은 src/config/index.ts에서 정규화되며, 헬퍼 게터(helper getters)를 통해 src/teamcity/config.ts에서 사용됩니다.
사용 예시 (Usage Examples)
AI 코딩 어시스턴트와 통합한 후:
"feature 브랜치에서 프론트엔드 빌드하기"
"어젯밤 테스트가 실패한 이유는 무엇인가요?"
"최신 빌드로 스테이징 배포하기"
...
도구 응답 및 페이지네이션 (Tool Responses and Pagination)
도구 응답(Responses): 도구들은 이제 일관된 MCP 콘텐츠를 반환합니다. 목록/조회(list/get) 작업의 경우, content[0].text에 JSON 문자열이 포함됩니다. 예시 형태: { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } 또는 { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }.
페이지네이션(Pagination): 대부분의 list_* 도구는 pageSize, maxPages, 그리고 all을 허용합니다:
pageSize는 페이지당 항목 수를 제어합니다.all: true는 최대 maxPages까지 여러 페이지를 가져옵니다.list_builds의 레거시 count는 호환성을 위해 유지되었지만, pageSize 사용이 권장됩니다.
유효성 검사 및 오류(Validation and Errors)
- 입력 유효성 검사(Input validation): 도구의 입력은 Zod 스키마로 검증되며, 유효하지 않은 입력은
success: false 및 error.code = VALIDATION_ERROR를 포함하는 구조화된 오류 페이로드(JSON 문자열)와 함께 응답 콘텐츠에 반환됩니다.
- 오류 형식 지정(Error shaping): 오류는 전역 핸들러를 통해 일관되게 형식 지정됩니다. 프로덕션 환경에서는 메시지가 정리될 수 있으며, 민감한 값(예: 토큰)은 로그에서 마스킹 처리됩니다.
API 사용법(API Usage)
import { TeamCityAPI } from '@/api-client';
...
참고: src/teamcity/index.ts에서 내보낸 레거시 헬퍼는 호환성을 위해서만 남아 있으며 플레이스홀더 구현을 포함합니다. 워크플로우를 자동화할 때는 MCP 도구(위의 참조 확인) 또는 여기에 표시된 TeamCityAPI 사용이 권장됩니다.
개발(Development)
CI에서의 번들 분석(Bundle analysis in CI)
CI 워크플로우는 npm run build:bundle을 실행하고, javascript-bundle 플러그인을 사용하여 생성된 coverage/bundles JSON을 codecov/codecov-action으로 업로드합니다.
프로젝트 구조(Project Structure)
teamcity-mcp/
├── src/ # 소스 코드
│ ├── tools.ts # 모든 87개 MCP 도구 정의
...
API 문서(API Documentation)
MCP 서버는 TeamCity 작업을 위한 도구들을 노출합니다. 각 도구는 특정 TeamCity REST API 엔드포인트에 해당합니다:
빌드 관리(Build Management)
TriggerBuild: 새 빌드 대기열 추가GetBuildStatus: 빌드 진행 상황 확인FetchBuildLog: 빌드 로그 검색ListBuilds: 기준별 빌드 검색
테스트 분석 (Test Analysis)
ListTestFailures: 실패한 테스트 목록 가져오기GetTestDetails: 상세 테스트 정보 조회AnalyzeBuildProblems: 실패 원인 식별
설정 (Configuration) (Full Mode 전용)
create_build_config: 다음 기능을 완벽하게 지원하는 새로운 TeamCity 빌드 구성을 생성합니다:
- 인증을 사용한 VCS 루트(Git, SVN, Perforce)
- 빌드 단계(script, Maven, Gradle, npm, Docker, PowerShell)
- 트리거(VCS, 스케줄, finish-build, maven-snapshot)
- 파라미터 및 템플릿 기반 구성
- 인자 세부 정보 및 추가 옵션은 MCP Tool Reference를 참조하십시오.
clone_build_config: 기존 구성을 프로젝트 내 원하는 곳으로 복제하며, 단계(steps), 트리거(triggers), 파라미터는 그대로 유지됩니다.update_build_config: 구성의 이름, 설명, 아티팩트 규칙, 일시 중지 상태를 조정합니다.manage_build_steps: 단일 도구 인터페이스를 통해 빌드 단계에 추가, 업데이트, 제거 또는 순서 변경을 수행합니다.manage_build_triggers: 모든 속성 지원과 함께 빌드 트리거를 추가하거나 삭제합니다.create_vcs_root & add_vcs_root_to_build: VCS 루트를 정의하고 이를 빌드 구성에 연결합니다.
추가 정보: 현재 MCP 구현과 일치하는 확장된 워크플로우 및 예제는 docs/TEAMCITY_MCP_TOOLS_GUIDE.md를 참조하십시오.
기여 (Contributing)
기여를 환영합니다! 자세한 내용은 [CONTRIBUTING.md]를 참조하십시오.
보안 (Security)
토큰 관리 (Token Management)
- 환경 변수 또는 설정 파일(
.env.example 참조)을 통해 TEAMCITY_TOKEN을 구성하십시오. 실제 토큰은 절대 커밋하지 마십시오.
- 최소한의 필수 권한을 가진 토큰을 사용하십시오. 읽기 전용(read-only) 토큰은 대부분의 개발 모드(Dev mode) 작업에 적합합니다.
- 토큰 기반 인증만 지원하며, MCP 서버는 사용자 이름/비밀번호를 지원하지 않습니다.
- 로그에는 토큰을 포함한 민감한 값이 마스킹(redact)됩니다.
