TeamCity 构建失败根因分析 MCP 服务

TeamCity QA Intelligence

Read-only MCP server for AI-assisted root-cause analysis of TeamCity build failures. Package and server name: teamcity-qa-mcp.

The problem

When a CI test run goes red, finding out why is manual detective work: open the build, copy stack traces, scan the log, check what changed, compare with the previous build, search whether the same test failed before. For a build with dozens of failures this takes serious time — and most of it is mechanical data gathering, not thinking.

The solution

This MCP server gives any MCP-compatible AI client structured, compact access to TeamCity data: builds, failed tests, logs, changes, history, diffs. The AI does the reasoning — classifying a failure as a code change (with the commit and author), flaky behavior, or an infrastructure problem — while the server does the data retrieval and normalization. The division of labor is strict: the server never guesses, the AI never scrapes.

Output of /generate-report: eleven of the fourteen failures collapse into one cross-config root cause. All data in this sample is fictional.

Is this for you?

Works well if your team runs tests on TeamCity, you triage red builds regularly, and a single failure often takes down many tests at once.

Not for you if your CI is Jenkins, GitHub Actions, or GitLab — this reads the TeamCity REST API and nothing else. Or if you want automated remediation: it reads and explains, it never fixes or reruns anything.

Features

• Read-only by design — no builds triggered, no tests muted, nothing written to TeamCity. Every API call is a GET. See Data, permissions & scope.
• Multi-config analysis — aggregate failures across a list of build configurations or a whole project (nested subprojects included), with cross-config root-cause clusters: the same error hitting several configurations at once is a strong infrastructure signal.
• Flexible targeting — key tools accept a single build configuration, a list, or a project; with no target they use the configured default.
• Root-cause clustering — "43 failures" becomes "1 root cause: AuthException 503, affects 43 tests".
• Compact JSON responses optimized for LLM consumption; graceful degradation when data is unavailable.
• Claude plugin included (plugin/) — slash commands for triage, comparison, flaky review, and a self-contained HTML health report.
• Prompts for any MCP client (prompts/) — the same workflows as ready-to-paste prompts for Cursor, VS Code Copilot, JetBrains AI, and others.
• stdio transport — works with Claude Code, Claude Desktop, Cursor, and any other MCP-compatible client.

Requirements

• Node.js 22 or newer — Node.js 24 LTS recommended; Node.js 20 reached end-of-life and is not supported
• An MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, VS Code Copilot, JetBrains AI, or any other
• A TeamCity server whose REST API is reachable from your machine
• A TeamCity access token — see Configuration
• About 10 minutes for the whole setup

Installation

One command for Claude Code — everything is configured inline:

claude mcp add --scope user --transport stdio teamcity-qa-mcp \
  --env TEAMCITY_URL=https://your-teamcity.com \
  --env TEAMCITY_TOKEN=your-token \
  --env TEAMCITY_BUILD_TYPE_ID=Your_BuildConfig_Id \
  -- npx -y teamcity-qa-mcp

No cloning, no source code, no .env file needed.

Scope options: --scope user makes the server available across all projects. Use --scope project to share config via .mcp.json in the repo, or omit the flag for local (current project only).

claude mcp add --scope user --transport stdio teamcity-qa-mcp \
  --env TEAMCITY_URL=https://your-teamcity.com \
  --env TEAMCITY_TOKEN=your-token \
  --env TEAMCITY_BUILD_TYPE_ID=Your_BuildConfig_Id \
  -- npx -y git+https://github.com/kate-horshchar/teamcity-qa-mcp.git

Claude Desktop

npx -y teamcity-qa-mcp setup-desktop \
  --url https://your-teamcity.com \
  --token your-token \
  --build-type Your_BuildConfig_Id

Then restart Claude Desktop.

Claude plugin (optional)

This repository is also a plugin marketplace. In Claude Code:

/plugin marketplace add kate-horshchar/teamcity-qa-mcp
/plugin install teamcity-qa@teamcity-qa-mcp

See plugin/README.md for the command list and Cowork organization install; non-Claude clients can use prompts/ instead.

git clone https://github.com/kate-horshchar/teamcity-qa-mcp.git
cd teamcity-qa-mcp
npm install                # also compiles TypeScript into dist/
cp .env.example .env       # Windows: copy .env.example .env

claude mcp add --transport stdio teamcity-qa-mcp \
  --env TEAMCITY_URL=https://your-teamcity.com \
  --env TEAMCITY_TOKEN=your-token \
  --env TEAMCITY_BUILD_TYPE_ID=Your_BuildConfig_Id \
  -- node /absolute/path/to/teamcity-qa-mcp/dist/index.js

npx tsx scripts/smoke-test.ts

Configuration

How to get your TeamCity API token

1. Log in to your TeamCity instance
2. Navigate to your profile settings → Access Tokens
3. Create a new token and copy the value — you will not see it again
4. Put it in your MCP client configuration (the --env flag above) or in a .env file

TeamCity tokens inherit the permissions of the account that creates them — there is no read-only switch on the token itself. Create the token from an account whose role on the target projects is view-only; the built-in Project viewer role is enough for everything this server does.

Data, permissions & scope

What it reads. Builds and their status, test results and failure messages, stack traces, build logs, and the commits associated with a build. Every request is a GET.

What leaves your machine. The server talks only to your TeamCity instance. But the data it returns is handed to your AI client, which sends it to whichever model provider that client uses — so build logs, stack traces, commit messages and author names are part of what you share with that provider. Point the server at build configurations you are comfortable sharing that way.

Where credentials live. The token comes from environment variables in your AI client's MCP configuration. set_auth_token and set_build_type_id update it at runtime and write the new value to the config files they find — ~/.claude.json, claude_desktop_config.json, and a .env in the current directory. They only touch keys that already exist in those files.

What it never does. Never triggers a build. Never mutes, ignores, or edits a test. Never writes anything to TeamCity. No telemetry, no analytics, no external service of any kind.

Available Tools

Documentation & examples

• Getting started — from zero to the first analysis
• Root cause detection — how the AI separates code changes, flaky tests, and infrastructure
• Multi-config analysis — targets, aggregation, and cost controls
• Claude plugin — installation and commands
• Examples — anonymized end-to-end scenarios, including a sample HTML report

Feedback

Ideas, feedback, and bug reports are welcome — open an issue.

If you are trying it for the first time, the most useful thing you can report is where Getting started broke down for you.

Roadmap

Planned work lives in GitHub Issues — the enhancement label is the roadmap.

Versioning & releases

Semantic versioning; package.json is the single source of the version. Every release is a git tag with notes in CHANGELOG.md and a GitHub Release. Release process: RELEASING.md.