TeamCity CI/CD

readonly-mcp-teamcity

一个只读的模型上下文协议（MCP）服务，可让 AI Agent 探索 JetBrains TeamCity 服务：项目、构建配置、构建、日志、测试结果、问题、队列、Agent 和 VCS 更改。共 29 个工具，全部只读。

快速开始

安装好 uv 后，无需安装其他内容：

claude mcp add teamcity \
  -e TEAMCITY_BASE_URL=https://teamcity.example.com \
  -e TEAMCITY_TOKEN=your-token \
  -- uvx readonly-mcp-teamcity

uvx 会将软件包下载到缓存的隔离环境中并运行。 需要 Python 3.11 或更高版本。

只读是设计使然。 此服务只会发出 GET 请求（如果 HTTP 客户端新增任何其他方法，测试就会失败）。它无法在 TeamCity 中触发、取消、固定、添加标签或修改任何内容，并且每个工具都标注了 readOnlyHint。请在 TeamCity 端将令牌设为只读，作为第二道防线：参见 令牌。阅读关于此服务的文章以及我为何构建只读 MCP 服务。

令牌

在 Profile → Access Tokens 下创建令牌。将 Permissions scope 设为 Limit per project，选择根项目（或 Agent 应该能查看的项目），并选择 Read-only 预设。即使客户端行为异常，这种范围的令牌也无法更改任何内容。

Read-only 预设会选择 TeamCity 标记为只读的 14 个 VIEW_* 权限，其中包括用于 Agent 详情和服务设置的全局权限。令牌不会获得超出其所有者权限的权限：使用仅拥有 Project viewer 角色的用户所创建的令牌时，Agent 工具仍可正常工作；get_server_health 会报告指标不可用，但仍会返回健康项。已在 TeamCity 2026.2.1 上验证：预设令牌无法固定构建（HTTP 403）。

工具

项目

工具	描述
search_projects	按名称、ID 或父级搜索项目；浏览层级结构。
get_project_details	项目完整信息：子项目、构建配置、参数。

构建配置

工具	描述
search_build_configs	按项目 ID、构建类型 ID 或暂停状态进行结构化搜索。
find_build_config	对配置名称和项目路径进行模糊搜索；标记不明确的匹配项并列出匹配项目。
get_build_config_details	步骤、触发器、参数、VCS 根目录、设置、Agent 要求。
get_build_config_branches	配置可以构建的分支，以及默认/活动状态。

构建

工具	描述
search_builds	搜索构建历史记录，可按配置、项目、状态、分支、日期等筛选。
get_build_details	单个构建：状态、Agent、修订版本、参数、依赖项、测试摘要、标签。
get_build_statistics	数值指标：耗时、测试数量、覆盖率、构件大小。
get_build_chain	快照依赖链的上游（依赖项）和下游（依赖者）。

日志

工具	描述
get_build_log	分页获取日志，支持 tail 和行范围。
search_build_log	在构建日志中进行全文搜索，并显示上下文。

测试与问题

工具	描述
diagnose_build	一次调用即可了解构建失败原因：问题、失败的测试（未静音的优先）以及日志中的错误行。
get_build_test_results	构建中的测试记录，可按状态筛选。
get_test_details	单个测试记录：失败原因、历史区间、静音/调查状态。
get_build_problems	结构化的失败原因（编译、退出代码、依赖项）。
search_investigations	按项目、构建配置或负责人查找正在进行的调查。
list_muted_tests	当前已静音的测试，以及其范围、静音者和原因。

基础设施

工具	描述
get_build_queue	正在等待 Agent 的构建，以及等待原因。
search_agents	构建 Agent 的连接/授权/启用状态及当前构建。
list_agent_pools	Agent 池及其 Agent 和项目数量。
get_agent_details	单个 Agent 的状态，包括启用/授权说明、上次活动时间和当前构建。
list_build_artifacts	浏览构建的制品目录树（一级目录）。
get_build_artifact_content	读取文本制品（限制大小，支持按行分页）。
search_changes	按构建、配置、项目、提交者或起始提交查找 VCS 变更（提交）。
get_change_details	单个变更及其完整的已修改文件列表。
resolve_teamcity_url	将 TeamCity 网页 URL 解析为项目/构建配置/构建/变更 ID。
get_server_info	TeamCity 版本、构建编号和运行时长。
get_server_health	服务器健康状况项目及运行时指标（CPU、内存、队列）。

安装

无需安装即可运行（推荐）：

uvx readonly-mcp-teamcity

或者将其安装到环境中：

uv tool install readonly-mcp-teamcity   # or: pip install readonly-mcp-teamcity

Docker

该镜像通过 8080 端口提供可流式 HTTP 传输。此传输没有身份验证，因此只能将其发布到主机的环回地址：

docker run --rm \
  -e TEAMCITY_BASE_URL=https://teamcity.example.com \
  -e TEAMCITY_TOKEN=your-token \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/desty2k/readonly-mcp-teamcity:latest

配置

所有配置均来自 TEAMCITY_* 环境变量。

变量	必填	默认值	描述
TEAMCITY_BASE_URL	是	—	TeamCity 服务基础 URL（例如 https://teamcity.example.com）。
TEAMCITY_TOKEN	是	—	REST API Bearer 令牌。请参阅令牌。
TEAMCITY_TIMEOUT	否	30	HTTP 请求超时时间（秒）。
TEAMCITY_MAX_RETRIES	否	3	对瞬时网络错误/5xx 错误的重试次数。
TEAMCITY_POOL_MAX_CONNECTIONS	否	20	httpx 连接池大小。
TEAMCITY_DEFAULT_LIMIT	否	50	列表工具的默认页面大小。
TEAMCITY_MAX_LIMIT	否	500	最大页面大小。
TEAMCITY_INDEX_REFRESH_INTERVAL	否	300	模糊索引刷新的间隔秒数。加载失败时会更快重试。
TEAMCITY_LOG_CACHE_MAX_BYTES	否	67108864	构建日志缓存的大小上限。运行中的构建日志不会被缓存。
TEAMCITY_LOG_CACHE_TTL	否	300	已完成构建的日志缓存保留秒数。
TEAMCITY_TRANSPORT	否	stdio	stdio、http 或 sse。
TEAMCITY_HTTP_HOST	否	127.0.0.1	http/sse 的绑定地址。这些传输没有身份验证；绑定到非环回地址时会记录警告。
TEAMCITY_HTTP_PORT	否	8080	http/sse 传输的端口。
TEAMCITY_LOG_FORMAT	否	json	json（生产环境）或 text（本地开发）。
TEAMCITY_LOG_LEVEL	否	INFO	DEBUG、INFO、WARNING 或 ERROR。

请参阅 .env.example 获取可直接复制粘贴的模板。

OpenTelemetry 跟踪

跟踪为可选功能，禁用时不会执行任何操作。基础安装不包含 OTel SDK；安装额外组件并启用后，即可为每次上游 TeamCity 调用导出 span：

pip install 'readonly-mcp-teamcity[otel]'
export TEAMCITY_OTEL_ENABLED=true
export TEAMCITY_OTEL_ENDPOINT=http://localhost:4317   # optional; falls back to OTEL_EXPORTER_OTLP_ENDPOINT

变量	默认值	描述
TEAMCITY_OTEL_ENABLED	false	跟踪总开关。
TEAMCITY_OTEL_SERVICE_NAME	readonly-mcp-teamcity	每个 span 上的 service.name。
TEAMCITY_OTEL_ENDPOINT	unset	OTLP 收集器端点。
TEAMCITY_OTEL_PROTOCOL	grpc	grpc 或 http/protobuf。
TEAMCITY_OTEL_CONSOLE_EXPORT	false	同时将 span 输出到 stderr。

MCP 客户端配置

Claude Desktop

将以下内容添加到 claude_desktop_config.json（macOS 上的 ~/Library/Application Support/Claude/，Windows 上的 %APPDATA%\Claude\）：

{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": ["readonly-mcp-teamcity"],
      "env": {
        "TEAMCITY_BASE_URL": "https://teamcity.example.com",
        "TEAMCITY_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

请参阅快速开始。

对比

截至 2026 年 11 月。依赖这些信息之前，请先查看各项目本身。

	本服务	JetBrains MCP (2026.1+)	Daghis 2.12.12	itcaat 1.0.8	kate-horshchar 1.4.0
写入操作	按设计不支持	默认安全模式下可创建个人构建；brave 模式下支持更多操作	默认可触发和取消；Agent 可切换到完整模式	可触发、取消、固定、添加标签；没有关闭开关	无，仅支持 GET
运行位置	你的机器	TeamCity 服务端（/app/mcp）	你的机器	你的机器	你的机器
根据模糊名称查找配置	基于名称和项目路径的模糊索引	未说明	仅定位器	定位器部分匹配	不支持
粘贴 TeamCity URL	支持现代、简短和旧版 URL	未说明	不支持	不支持	不支持

来源：JetBrains AI Agent 集成、 JetBrains/teamcity-mcp、 Daghis/teamcity-mcp、 itcaat/teamcity-mcp、 kate-horshchar/teamcity-qa-mcp。 JetBrains 插件 README 与其帮助页面对 brave 模式是否默认开启说法不一；请检查你的服务设置。

如果你希望 Agent 对 TeamCity 执行操作，请使用内置服务。如果你希望 Agent 只查看信息，请使用此服务。

示例问题

• “查找 auth 服务的部署流水线。”
• “显示 Proj_Build 最近 10 次构建，以及哪些构建失败了。”
• “构建 12345 为什么失败？”（调用一次 diagnose_build）
• “该构建中哪些测试失败了，错误是什么？”
• “在构建日志中搜索 OutOfMemoryError。”
• “目前哪些 Agent 离线？”
• “构建队列中有哪些内容，为什么在等待？”
• “谁在调查 Payments 项目中的故障？”
• “有哪些提交包含在此构建中？”
• “解析 https://teamcity.example.com/buildConfiguration/Proj_Build/12345。”

开发

git clone https://github.com/desty2k/readonly-mcp-teamcity
cd readonly-mcp-teamcity
uv sync --all-extras
uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

针对真实服务执行实时冒烟测试（从 .env 读取凭据）：

uv run python tests/smoke_test.py

许可证

MIT — 参见 LICENSE。