teamcity

TeamCity MCP 服务

一个模型控制协议（MCP）服务，可连接 AI 编码助手与 JetBrains TeamCity CI/CD 服务，并将 TeamCity 操作作为 MCP 工具提供。

说明

项目状态（2026 年 10 月）：稳定，低频维护。 本项目已实现最初目标，目前不再积极开发。它仍可正常工作并可继续安装；问题和 PR 可能需要较长时间才能得到回复，甚至不会收到回复，安全修复则尽力而为。

JetBrains 现在为 TeamCity 提供官方 AI 集成——内置于 TeamCity 2026.1+ 的 MCP 服务，以及带有可安装 Agent 技能的 TeamCity CLI——对于大多数工作流而言，这是更好的默认选择。在采用本项目之前，请先参阅下文的与 JetBrains 官方工具的比较。

概述

TeamCity MCP 服务让使用 AI 编码助手（Claude Code、Cursor、Windsurf）的开发者能够通过 MCP 工具直接在开发环境中与 TeamCity 交互。

从 1.x 升级？ 2.0.0 版将 15 个工具从 Dev 模式移至 Full 模式，包括队列管理、Agent 兼容性检查和服务健康监控。如果你在 Dev 模式下依赖这些工具，请切换到 MCP_MODE=full，或使用运行时模式切换（v2.1.0+）。详情请参阅 CHANGELOG.md。

功能

🚀 两种运行模式

• Dev 模式（默认）：安全的 CI/CD 操作（31 个工具，约 14k 个上下文令牌）

  • 触发构建并监控状态
  • 获取构建日志并检查测试失败
  • 列出项目、配置和队列
  • 读取参数并排查问题

• Full 模式：完整的基础设施管理（87 个工具，约 26k 个上下文令牌）

  • 包含 Dev 模式的全部功能，另有：
  • 创建和克隆构建配置
  • 管理构建步骤、触发器和依赖项
  • 配置 VCS 根目录和 Agent
  • 对参数执行完整的 CRUD 操作（构建配置、项目和输出参数）
  • 队列管理和服务管理

运行时模式切换（v2.1.0+）： 使用 get_mcp_mode 和 set_mcp_mode 工具即可在运行时切换模式，无需重启。支持通知的 MCP 客户端会自动看到工具列表更新。

完整的 87 个工具列表及其在各模式下的可用情况，请参阅 工具模式矩阵。

🎯 主要功能

• 触发并监控构建、获取日志并检查测试失败
• 使用基于令牌的方式对 TeamCity 进行身份验证；日志中会隐藏敏感值
• 现代化架构：采用单例客户端的简单直接实现
• 注重性能：启动快速，开销极低
• 代码库整洁，模块边界清晰

与 JetBrains 官方工具的比较

截至 2026 年 10 月（TeamCity 2026.2、TeamCity CLI 1.6），JetBrains 为 AI Agent 提供了两种官方一方方案，均已正式发布并获得官方支持：

• 内置 MCP 服务 — 每个 TeamCity 2026.1 及更高版本的服务（Cloud 和 On-Premises）都在 <server-url>/app/mcp 提供 MCP 端点，因此无需安装任何内容。它有意保持工具集精简：构建日志、通用 REST API GET/POST 直通工具，以及（自 2026.2 起）流水线工具。默认情况下，它在安全模式下运行，Agent 可以读取和排队个人构建；选择启用“勇敢模式”后，它便可以发送任意 REST POST 请求，以及编辑或删除流水线。自 2026.2 起，你还可以使用 OAuth 登录，无需粘贴访问令牌。
• TeamCity CLI — 一个开源的 teamcity 命令（适用于 TeamCity 2020.1 及更高版本），并提供可安装的 Agent 技能（teamcity skill install），支持 Claude Code、Cursor 和其他 Agent。它涵盖运行、日志、测试、队列、Agent、池、项目、VCS 根目录、参数和流水线；当需要时，可通过 teamcity api 回退到原始 REST 访问；还提供只读模式（TEAMCITY_RO=1）。JetBrains 自己的文档称它是两种方案中覆盖范围更广的一种。

teamcity-mcp 的出现早于这些工具，且与它们有大量重叠。如今，官方工具是更好的默认选择。teamcity-mcp 目前仍提供的功能比以往更有限：

• 适用于早于 2026.1 的服务的 MCP 服务。 如果你的客户端只支持 MCP，而 TeamCity 服务早于内置端点所需版本，此工具仍可使用（TeamCity 2020.1 及更高版本）。
• 专门构建的 MCP 工具，而非 REST 直通。 它提供 87 个带类型的工具（由 Dev/Full 模式控制），因此 Agent 无需了解 REST 路径和定位符；它还覆盖由 PUT/DELETE 支持的操作（例如启用 Agent 或删除参数），而内置 MCP 的通用 GET/POST 工具无法执行这些操作。

JetBrains 的工具发展很快，因此这里不逐项比较功能（这类比较很快就会过时），请查阅最新文档并选择适合你的方案：

• TeamCity 2026.2 公告 — 内置 MCP 的流水线工具、勇敢模式和 OAuth
• TeamCity 2026.1 公告 — 官方 AI 集成首次亮相
• AI Agent 集成文档 — 内置 MCP、其工具，以及安全模式与勇敢模式
• TeamCity CLI 文档和 Agent 技能 — 终端与 Agent 技能方案

如果你熟悉 JetBrains 的 CLI，可能完全不需要这个项目。它仍采用 MIT 许可证，并可安装，用于实现内置工具尚未覆盖的功能——如果想进一步拓展，也可以自行派生。

安装

前置条件

• Node.js >= 20.10.0（已在 CI 中测试 LTS 版本 20、22、24）
• 具有 REST API 访问权限的 TeamCity Server 2020.1 及更高版本
• TeamCity 身份验证令牌

快速开始

# Clone the repository
git clone https://github.com/Daghis/teamcity-mcp.git
cd teamcity-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your TeamCity URL and token

# Run in development mode
npm run dev

npm 包

通过 npx 运行 MCP 服务（需要 Node 20.x）。在命令中设置 TeamCity 环境变量，或在工作目录中通过 .env 文件设置。

# One-off run (inline envs)
TEAMCITY_URL="https://teamcity.example.com" \
TEAMCITY_TOKEN="<your_token>" \
MCP_MODE=dev \
npx -y @daghis/teamcity-mcp

# Or rely on .env in the current directory
npx -y @daghis/teamcity-mcp

Claude Code

• 添加 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": {
      "command": "npx",
      "args": [
        "-y",
        "@daghis/teamcity-mcp",
        "--url",
        "https://teamcity.example.com",
        "--token",
        "YOUR_TOKEN"
      ]
    }
  }
}

也可以使用配置文件来提高安全性（令牌不会显示在进程列表中）：

{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": ["-y", "@daghis/teamcity-mcp", "--config", "C:\\path\\to\\teamcity.env"]
    }
  }
}

配置

环境变量由 Zod 集中验证。支持的变量及默认值如下：

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# TeamCity Configuration (aliases supported)
TEAMCITY_URL=https://teamcity.example.com
TEAMCITY_TOKEN=your-auth-token
# Optional aliases:
# TEAMCITY_SERVER_URL=...
# TEAMCITY_API_TOKEN=...

# MCP Mode (dev or full)
MCP_MODE=dev

# Optional advanced TeamCity options (defaults shown)
# Connection
# TEAMCITY_TIMEOUT=30000
# TEAMCITY_MAX_CONCURRENT=10
# TEAMCITY_KEEP_ALIVE=true
# TEAMCITY_COMPRESSION=true

# Extra headers attached to every TeamCity request — useful when TeamCity
# sits behind a reverse proxy that gates access on custom headers (e.g.
# Cloudflare Zero Trust service tokens). One env var per header; the part
# after `TEAMCITY_HEADER_` is used verbatim as the HTTP header name.
# Example (note the literal hyphens — most shells need quoting):
# TEAMCITY_HEADER_CF-Access-Client-Id=<id>
# TEAMCITY_HEADER_CF-Access-Client-Secret=<secret>

# Retry
# TEAMCITY_RETRY_ENABLED=true
# TEAMCITY_MAX_RETRIES=3
# TEAMCITY_RETRY_DELAY=1000
# TEAMCITY_MAX_RETRY_DELAY=30000

# Pagination
# TEAMCITY_PAGE_SIZE=100
# TEAMCITY_MAX_PAGE_SIZE=1000
# TEAMCITY_AUTO_FETCH_ALL=false

# Circuit Breaker
# TEAMCITY_CIRCUIT_BREAKER=true
# TEAMCITY_CB_FAILURE_THRESHOLD=5
# TEAMCITY_CB_RESET_TIMEOUT=60000
# TEAMCITY_CB_SUCCESS_THRESHOLD=2

这些值会在 src/config/index.ts 中标准化，并通过辅助 getter 在 src/teamcity/config.ts 中使用。

使用示例

与 AI 编码助手集成后：

"Build the frontend on feature branch"
"Why did last night's tests fail?"
"Deploy staging with the latest build"
"Create a new build config for the mobile app"

工具响应与分页

• 响应：工具现在会返回格式一致的 MCP 内容。对于列表／获取操作，content[0].text 包含一个 JSON 字符串。示例结构： { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } 或 { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }。
• 分页：大多数 list_* 工具都接受 pageSize、maxPages 和 all：
  • pageSize 控制每页的项目数。
  • all: true 会获取多页数据，最多不超过 maxPages。
  • list_builds 中的旧版 count 参数为保持兼容而保留，但更推荐使用 pageSize。

验证与错误

• 输入验证：工具输入使用 Zod 架构进行验证；无效输入会在响应内容中返回结构化错误负载（JSON 字符串），其中 success: false 且 error.code = VALIDATION_ERROR。
• 错误格式化：错误由全局处理器统一格式化。在生产环境中，消息可能会经过清理；敏感值（例如令牌）会在日志中脱敏。

API 用法

import { TeamCityAPI } from '@/api-client';

// Get the API client instance
const api = TeamCityAPI.getInstance();

// List projects
const projects = await api.listProjects();

// Get build status
const build = await api.getBuild('BuildId123');

// Trigger a new build
const newBuild = await api.triggerBuild('BuildConfigId', {
  branchName: 'main',
});

注意： 从 src/teamcity/index.ts 导出的旧版辅助函数仅为保持兼容而保留，其中包含占位实现。自动化工作流时，优先使用 MCP 工具（参见上方链接的参考文档）或此处展示的 TeamCityAPI。

开发

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

# Build for production
npm run build

# Analyze bundle for Codecov
npm run build:bundle

CI 中的 Bundle 分析

CI 工作流会运行 npm run build:bundle，并使用带有 javascript-bundle 插件的 codecov/codecov-action 上传生成的 coverage/bundles JSON 文件。

项目结构

teamcity-mcp/
├── src/                    # Source code
│   ├── tools.ts           # All 87 MCP tool definitions
│   ├── server.ts          # MCP server setup
│   ├── api-client.ts      # TeamCity API singleton
│   ├── config/            # Configuration with Zod validation
│   ├── teamcity/          # Domain logic (build, agent, config managers)
│   ├── teamcity-client/   # Auto-generated OpenAPI client
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Logger, MCP helpers, pagination
├── tests/                  # Unit and integration tests
├── docs/                   # Documentation
└── scripts/                # Build and maintenance scripts

API 文档

MCP 服务提供用于 TeamCity 操作的工具。每个工具都对应特定的 TeamCity REST API 端点：

构建管理

• TriggerBuild - 将新构建加入队列
• GetBuildStatus - 检查构建进度
• FetchBuildLog - 获取构建日志
• ListBuilds - 按条件搜索构建

测试分析

• ListTestFailures - 获取失败的测试
• GetTestDetails - 获取详细的测试信息
• AnalyzeBuildProblems - 识别失败原因

配置（仅限 Full Mode）

• create_build_config - 创建新的 TeamCity 构建配置，全面支持：
  • 带身份验证的 VCS 根（Git、SVN、Perforce）
  • 构建步骤（脚本、Maven、Gradle、npm、Docker、PowerShell）
  • 触发器（VCS、计划、构建完成、maven-snapshot）
  • 参数和基于模板的配置
  • 有关参数详情和其他选项，请参阅 MCP 工具参考。
• clone_build_config - 将现有配置复制到任意项目，并保留步骤、触发器和参数。
• update_build_config - 调整配置的名称、描述、制品规则和暂停状态。
• manage_build_steps - 通过单个工具界面添加、更新、移除或重新排序构建步骤。
• manage_build_triggers - 添加或删除构建触发器，并全面支持属性。
• create_vcs_root 和 add_vcs_root_to_build - 定义 VCS 根并将其附加到构建配置。

另请参阅 docs/TEAMCITY_MCP_TOOLS_GUIDE.md，了解与当前 MCP 实现相符的扩展工作流和示例。

贡献

欢迎贡献！详情请参阅 CONTRIBUTING.md。

安全

令牌管理

• 通过环境变量或配置文件设置 TEAMCITY_TOKEN（参见 .env.example）；切勿提交真实令牌
• 使用权限满足最低需求的令牌；对于大多数 Dev mode 操作，只读令牌即可
• 仅支持基于令牌的身份验证；MCP 服务不支持用户名/密码
• 日志会对令牌等敏感值进行脱敏

模式选择

• 除非明确需要 Full mode，否则优先使用 Dev mode——这样可以限制错误配置或提示词注入造成的影响范围
• Full mode 支持破坏性操作（删除项目、管理 Agent），且这些操作不易撤销

网络安全

• 始终通过 HTTPS 连接 TeamCity；服务不会强制要求使用 HTTPS，但强烈建议这样做
• MCP 服务仅连接到已配置的 TeamCity URL；不会发起其他网络调用

AI 助手注意事项

• 构建日志、测试输出或其他 TeamCity 数据中的提示词注入可能会操纵 AI 助手
• Dev mode 提供的有限工具集可降低此类攻击的影响
• 所有操作都会以令牌关联用户的身份记录在 TeamCity 审计日志中
• 构建日志和测试失败详情可能包含敏感信息（机密、路径、内部 URL），这些信息会显示给 AI 助手

仓库安全

此仓库已启用 GitHub 机密扫描和推送保护。漏洞报告请参阅 SECURITY.md。

支持

• GitHub Issues：报告错误或申请功能
• 文档：请参阅此仓库中的 docs/ 文件夹

致谢

• 感谢 JetBrains TeamCity 提供出色的 CI/CD 平台
• 感谢 Anthropic 制定 Model Control Protocol 规范
• 感谢开源社区一直以来的支持
• 第三方许可证请参阅 THIRD_PARTY_NOTICES.md

---

为热爱高效 CI/CD 工作流的开发者倾情打造 ❤️