TeamCity MCP Server

A Model Control Protocol (MCP) server that bridges AI coding assistants with JetBrains TeamCity CI/CD server, exposing TeamCity operations as MCP tools.

Overview

The TeamCity MCP Server allows developers using AI-powered coding assistants (Claude Code, Cursor, Windsurf) to interact with TeamCity directly from their development environment via MCP tools.

Features

🚀 Two Operational Modes

• Dev Mode: Safe CI/CD operations

  • Trigger builds

  • Monitor build status and progress

  • Fetch build logs

  • Investigate test failures

  • List projects and configurations

• Full Mode: Complete infrastructure management

  • All Dev mode features, plus:

  • Create and clone build configurations

  • Manage build steps and triggers

  • Configure VCS roots and agents

  • Set up new projects

  • Modify infrastructure settings

🎯 Key Capabilities

• Trigger and monitor builds, fetch logs, and inspect test failures

• Token-based authentication to TeamCity; sensitive values redacted in logs

• Modern architecture: simple, direct implementation with a singleton client

• Performance-conscious: fast startup with minimal overhead

• Clean codebase with clear module boundaries

Installation

Prerequisites

• Node.js >= 20.10.0

• TeamCity Server 2020.1+ with REST API access

• TeamCity authentication token

Quick Start

npm Package

Run the MCP server via npx (requires Node 20.x). Set your TeamCity environment variables inline or via a .env in the working directory.

Claude Code

• Add the MCP:

  • claude mcp add [-s user] teamcity -- npx -y @daghis/teamcity-mcp

• With env vars (if not using .env):

  • claude mcp add [-s user] teamcity -- env TEAMCITY_URL="https://teamcity.example.com" TEAMCITY_TOKEN="tc_<your_token>" MCP_MODE=dev npx -y @daghis/teamcity-mcp

• Context usage (Opus 4.1, estimates):

  • Dev (default): ~14k tokens for MCP tools

  • Full (MCP_MODE=full): ~26k tokens for MCP tools

Configuration

Environment is validated centrally with Zod. Supported variables and defaults:

These values are normalized in src/config/index.ts and consumed by src/teamcity/config.ts via helper getters.

Usage Examples

Once integrated with your AI coding assistant:

Tool Responses and Pagination

• Responses: Tools now return consistent MCP content. For list/get operations, the content[0].text contains a JSON string. Example shape: { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } or { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }.

• Pagination: Most list_* tools accept pageSize, maxPages, and all:

  • pageSize controls items per page.

  • all: true fetches multiple pages up to maxPages.

  • Legacy count on list_builds is kept for compatibility but pageSize is preferred.

Validation and Errors

• Input validation: Tool inputs are validated with Zod schemas; invalid input returns a structured error payload in the response content (JSON string) with success: false and error.code = VALIDATION_ERROR.

• Error shaping: Errors are formatted consistently via a global handler. In production, messages may be sanitized; sensitive values (e.g., tokens) are redacted in logs.

API Usage

Note: The legacy helpers exported from src/teamcity/index.ts remain only for compatibility and include placeholder implementations. Prefer the MCP tools (see the reference linked above) or the TeamCityAPI shown here when automating workflows.

Development

Bundle analysis in CI

The CI workflow runs npm run build:bundle and uploads the generated coverage/bundles JSON using codecov/codecov-action with the javascript-bundle plugin.

Project Structure

API Documentation

The MCP server exposes tools for TeamCity operations. Each tool corresponds to specific TeamCity REST API endpoints:

Build Management

• TriggerBuild - Queue a new build

• GetBuildStatus - Check build progress

• FetchBuildLog - Retrieve build logs

• ListBuilds - Search builds by criteria

Test Analysis

• ListTestFailures - Get failing tests

• GetTestDetails - Detailed test information

• AnalyzeBuildProblems - Identify failure reasons

Configuration (Full Mode Only)

• create_build_config - Create new TeamCity build configurations with full support for:

  • VCS roots (Git, SVN, Perforce) with authentication

  • Build steps (script, Maven, Gradle, npm, Docker, PowerShell)

  • Triggers (VCS, schedule, finish-build, maven-snapshot)

  • Parameters and template-based configurations

  • See the MCP Tool Reference for argument details and additional options.

• clone_build_config - Duplicate existing configurations into any project, preserving steps, triggers, and parameters.

• update_build_config - Adjust names, descriptions, artifact rules, and pause state for a configuration.

• manage_build_steps - Add, update, remove, or reorder build steps through a single tool surface.

• manage_build_triggers - Add or delete build triggers with full property support.

• create_vcs_root & add_vcs_root_to_build - Define VCS roots and attach them to build configurations.

See also: docs/TEAMCITY_MCP_TOOLS_GUIDE.md for expanded workflows and examples that align with the current MCP implementation.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Security

• Configure TEAMCITY_TOKEN via environment (see .env.example); never commit real tokens

• Token-based authentication only

• Logs redact sensitive values

Support

• GitHub Issues: Report bugs or request features

• Documentation: See the docs/ folder in this repository

Acknowledgments

• JetBrains TeamCity for the excellent CI/CD platform

• Anthropic for the Model Control Protocol specification

• The open-source community for continuous support

Built with ❤️ for developers who love efficient CI/CD workflows