@daghis/teamcity-mcp

中文文档

2.12.15发布于 2026/11/07MITTypeScriptCommonJS构建来源已验证近 30 天下载 1万

TeamCity CI/CD 集成的模型控制协议服务器与 AI 编码助理

文档目录32 节

概览
特征
双业务模式
关键能力
比起JetBrains的官方工具
安装
先决条件
快速启动
npm 软件包
克劳德代码
窗口用户
配置
用法实例
工具响应和插座
校验和错误
API 使用量
发展
CI 中的装订分析
项目结构
API 文档
房舍管理
测试分析
配置( 完全模式)
捐款
警卫
托肯管理
模式选择
网络安全
AI 助理考虑
仓库安全
支助
承认

团队城 MCP 服务器

一个模型控制协议(MCP)服务器,将AI编码助手与JetBrains TeamCity CI/CD服务器相接,将TeamCity操作暴露为MCP工具.

[注] 项目状况(2026年10月):稳定,低调维护. 这是它所要做的事情,现在已不再在积极发展之中。它仍然有效,仍然可以安装;问题和PR可能会得到缓慢或没有反应,而安全修复是最佳的.

JetBrains现在为TeamCity(TeamCity)搭载了官方AI集成——一个MCP服务器被建入TeamCity 2026.1+和团队城市CLI 具有可安装的代理技能——这是大多数工作流程更好的默认. 见 比起JetBrains的官方工具 以下为收养前.

概览

TeamCity MCP Server允许使用AI动力编码助理(Claude Code, Cursor, Windsurf)的开发者通过MCP工具直接从开发环境与TeamCity互动.

从1.x升级? 2.0.0版本将15个工具从Dev移动到Full模式,包括队列管理,代理兼容性检查,以及服务器健康监测等. 如果您在 Dev 模式中依赖于这些工具, 请切换到 MCP_MODE=full 或使用运行时模式切换(v2.1.0+). 见变动情况详细情况.

特征

双业务模式

开发模式 (默认):安全 CI/CD 操作(31个工具,~14k上下文符)
- 触发器构建并监视状态
- 获取构建日志并检查测试失败
- 列出工程、配置和队列
- 读取参数并调查问题
完整模式: 完成基础设施管理(87个工具,~26k上下文符)
- 所有 Dev 模式特性, 外加 :
- 创建和克隆构建配置
- 管理构建步骤、触发和依赖
- 配置 VCS 根和代理
- 参数的完整 CRUD( 构建配置、项目和输出参数)
- 队列管理和服务器管理

运行时间模式切换(v2.1.0+): 运行时在模式间切换 get_mcp_mode 财务报告和审定财务报表 set_mcp_mode 工具 - 不需要重新启动。支持通知的MCP客户端会自动看到工具列表更新.

见工具模式矩阵用于87个工具的完整清单及其按模式的可用性.

关键能力

触发和监视器构建、获取日志并检查测试失败
基于 Token 对 TeamCity 的认证; 在日志中编辑的敏感值
现代架构:简单,有单通客户端的直接执行
性能意识:快速启动,间接费用最低
模块界限明确的清洁编码库

比起JetBrains的官方工具

截止2026年10月 (TeamCity 2026.2,TeamCity CLI 1.6),JetBrains为AI代理的两条一线航道,两者均普遍可用并获得官方支持:

内建的 MCP 服务器 – 每个 TeamCity 2026.1+ 服务器( Cloud and On-Premises) 都会在 <server-url>/app/mcp,所以没有安装。这是一个刻意的小工具: 建立日志,通用 REST API GET编号 :POST 通过工具,以及(自2026.2)管道工具。默认情况下, 它运行在一个安全模式中, 代理可以读取并排队列个人构建; 一个选择中的“ 勇敢模式” 允许它发送任意 REST POST 请求并编辑或删除管道。自2026.2起,您也可以与OAuth签约,而不是粘贴访问符.
团队城市CLI ——开源 teamcity 命令(TeamCity 2020.1+),具有可安装代理技能(teamcity skill installClaude Code, Cursor, 和其他探员的它覆盖运行,日志,测试,队列,代理,池,项目,VCS根,参数,以及管道,返回到原始的REST访问通过 teamcity api,并具有只读模式(TEAMCITY_RO=1JetBrains自己的文件将其描述为两个选项中更广泛的.

teamcity-mcp 预示着工具化和重合性很强. 官方工具是今天更好的默认. MCP仍然提供什么比以前更狭窄:

一个MCP服务器,服务于2026.1. 如果您的客户端只说MCP,而您的TeamCity服务器在内置端点之前就已经存在,这仍然可行(TeamCity 2020.1+).
目的性制造的MCP工具,而不是REST通过. 它暴露出87个打字工具(由 Dev/Full 模式指定),因此代理商不需要了解REST路径和定位器——它涵盖了由支持的操作 PUT编号 :DELETE (例如赋能剂或删除参数),内置的MCP通用 GET编号 :POST 工具无法到达.

JetBrains的工具正在迅速演变,因此与其在这里按特点进行对比(它会很快被扭曲),不如检查当前的文件并选择合适的:

2026.2号城市公告 ——管道工具,勇者模式,以及内置MCP的OAuth
TeamCity 2026.1 公告 ——官方AI整合首发地
AI 代理集成文件 ——内置的MCP,其工具,安全与勇敢模式
团队城市 CLI 文件财务报告和审定财务报表代理技能 ——终端+代理技能路径

如果你对JetBrains的CLI很满意,你可能根本不需要这个项目. 它仍然有麻省理工学院的许可,并且可以安装,不管内置设施还没有达到什么——如果你想自己更进一步,就把它叉开.

安装

先决条件

节点.js >= 20.1.0 (LTS版本20,22,24在CI测试)
TeamCity Server 2020.1+ 有 REST API 访问权限
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

克劳德代码

添加 MCP( 依赖 .env 用于配置 :
- claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
带有env vars(如果不使用.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 令牌
- 完整( E)MCP_MODE=full: MCP 工具的 ~ 26k 令牌

窗口用户

在 Windows 上, Claude 代码的 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 消耗量 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 } }。。。 .
PGination: 大多数列表QQ 工具被接受 pageSize, (中文(简体) ), maxPages,以及 all数字 :
- pageSize 每页控制项.
- all: true 获取多页 maxPages。。。 .
- 遗产 count 打开 list_builds 用于兼容,但 pageSize 优先选择.

校验和错误

输入验证: 用 Zod schemas 验证工具输入; 无效输入返回响应内容中的结构化错误有效载荷( JSON string) 与 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 中的装订分析

CI 工作流程运行 npm run build:bundle 并上传生成的 coverage/bundles 使用 JSON 软件 codecov/codecov-action 与 javascript-bundle 插件 .

项目结构

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 - 查明失败原因

配置( 完全模式)

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 (c) 扩大工作流程和实例,使之与当前的多边CP执行相一致.

捐款

我们欢迎捐款! 请看捐款额详细情况.

警卫

托肯管理

配置 TEAMCITY_TOKEN 通过环境变量或配置文件(参见 .env.example; 从不执行真实的标志
使用最小权限的指使; 只读指使为大多数 Dev 模式操作工作
仅基于托肯认证; MCP 服务器不支持用户名/ 密码字
日志编辑敏感值,包括符号

模式选择

偏爱 开发模式 除非明确需要完全模式——这限制了任何配置错误或迅速注射的爆炸半径
完整模式可以实现无法轻易消除的破坏性操作(项目删除、代理管理)

网络安全

总是使用 HTTPS 进行TeamCity 连接; 服务器不执行,而是强烈推荐
MCP 服务器只连接到配置的 TeamCity URL; 没有进行其他网络呼叫

AI 助理考虑

AI 助手可以通过在构建日志、测试输出或其他TeamCity数据中的即时注入来被操纵
Dev 模式的有限工具集可以减少这种攻击的影响
所有动作都出现在 TeamCity 的相关用户下的审计日志中
构建日志和测试失败细节可能包含AI助手可见的敏感信息(机密,路径,内部URL)

仓库安全

此寄存器已启用 GitHub 秘密扫描和推取保护。见警卫脆弱性报告.

支助

GitHub 问题 : 报告错误或请求特性
文号: docs/ 此仓库中的文件夹

承认

优秀CI/CD平台城市
用于示范控制议定书规格的
持续支持的开源社区
见第三次议会 NoTICES.md 第三方许可证

为喜欢高效 CI/ CD 工作流程的开发者所建 QQ

版本与发布记录

@daghis/teamcity-mcp 共发布 120 个版本，首次发布于 2025/09/12；过去 12 个月发布了 71 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`2.12.15`latest	2026/11/07	4 天前
`2.12.14`	2026/11/07	4 天前
`2.12.13`	2026/11/06	4 天前
`2.12.12`	2026/10/29	13 天前
`2.12.11`	2026/10/28	13 天前
`2.12.10`	2026/10/21	20 天前

关于 @daghis/teamcity-mcp 的常见问题

@daghis/teamcity-mcp 是什么？

TeamCity CI/CD 集成的模型控制协议服务器与 AI 编码助理

如何安装 @daghis/teamcity-mcp？

在项目目录运行 npm install @daghis/teamcity-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 teamcity-mcp，可以用 npx teamcity-mcp 直接运行。

@daghis/teamcity-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@daghis/teamcity-mcp 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@daghis/teamcity-mcp 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=20.19.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@daghis/teamcity-mcp 可以商用吗？

@daghis/teamcity-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@daghis/teamcity-mcp 的下载量有多少？

根据 npm 官方下载统计，@daghis/teamcity-mcp 在 2026/10/11 – 2026/11/09 这 30 天内被下载 10,295 次，日均约 343 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@daghis/teamcity-mcp 还在维护吗？

最新版本 2.12.15 发布于 2026/11/07（4 天前）；至今共发布 120 个版本，其中过去 12 个月发布了 71 个；首次发布于 2025/09/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。