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.

Upgrading from 1.x? Version 2.0.0 moved 15 tools from Dev to Full mode, including queue management, agent compatibility checks, and server health monitoring. If you relied on these tools in Dev mode, switch to MCP_MODE=full or use runtime mode switching (v2.1.0+). See CHANGELOG.md for details.

Features

🚀 Two Operational Modes

• Dev Mode (default): Safe CI/CD operations (31 tools, ~14k context tokens)

  • Trigger builds and monitor status
  • Fetch build logs and inspect test failures
  • List projects, configurations, and queue
  • Read parameters and investigate problems

• Full Mode: Complete infrastructure management (87 tools, ~26k context tokens)

  • All Dev mode features, plus:
  • Create and clone build configurations
  • Manage build steps, triggers, and dependencies
  • Configure VCS roots and agents
  • Full CRUD for parameters (build config, project, and output parameters)
  • Queue management and server administration

Runtime Mode Switching (v2.1.0+): Switch between modes at runtime using the get_mcp_mode and set_mcp_mode tools—no restart required. MCP clients that support notifications will see the tool list update automatically.

See the Tools Mode Matrix for the complete list of 87 tools and their availability by mode.

🎯 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

Choosing between teamcity-mcp and the built-in MCP

TeamCity 2026.1 ships with a built-in MCP endpoint at <server-url>/app/mcp exposing three tools: build log retrieval, a generic REST GET, and a build trigger (forced to personal=true). It is server-resident, requires no install, and is a sensible default for read-and-rerun workflows.

teamcity-mcp is a different shape: an 87-tool typed surface focused on AI-driven workflows that need writes, multi-server support, or pre-2026.1 compatibility.

Both can coexist. The built-in is a good first stop; teamcity-mcp is the power tool for everything the built-in doesn't reach.

For the design reasoning, see docs/strategy.md and docs/non-goals.md.

Installation

Prerequisites

• Node.js >= 20.10.0 (LTS versions 20, 22, 24 tested in CI)
• TeamCity Server 2020.1+ with REST API access
• TeamCity authentication token

Quick Start

# 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 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.

# 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

• Add the MCP (relying on .env for configuration):
  • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
• With env vars (if not using .env):
  • claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp
• With CLI arguments (recommended for Windows):
  • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev
• Add -s user to install user-wide instead of project-scoped (default)
• Context usage (Opus 4.1, estimates):
  • Dev (default): ~14k tokens for MCP tools
  • Full (MCP_MODE=full): ~26k tokens for MCP tools

Windows Users

On Windows, Claude Code's MCP configuration may not properly merge environment variables. Use CLI arguments as a workaround:

{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": [
        "-y",
        "@daghis/teamcity-mcp",
        "--url",
        "https://teamcity.example.com",
        "--token",
        "YOUR_TOKEN"
      ]
    }
  }
}

Or use a config file for better security (token not visible in process list):

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

Configuration

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

# 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

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:

"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"

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

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',
});

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

# 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

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

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 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

Token Management

• Configure TEAMCITY_TOKEN via environment variable or config file (see .env.example); never commit real tokens
• Use a token with minimal required permissions; read-only tokens work for most Dev mode operations
• Token-based authentication only; the MCP server does not support username/password
• Logs redact sensitive values including tokens

Mode Selection

• Prefer Dev mode unless Full mode is explicitly needed—this limits the blast radius of any misconfiguration or prompt injection
• Full mode enables destructive operations (project deletion, agent management) that cannot be easily undone

Network Security

• Always use HTTPS for TeamCity connections; the server does not enforce this but strongly recommends it
• The MCP server connects only to the configured TeamCity URL; no other network calls are made

AI Assistant Considerations

• AI assistants could be manipulated via prompt injection in build logs, test output, or other TeamCity data
• Dev mode's limited tool set reduces the impact of such attacks
• All actions appear in TeamCity's audit log under the token's associated user
• Build logs and test failure details may contain sensitive information (secrets, paths, internal URLs) that become visible to the AI assistant

Repository Security

This repository has GitHub secret scanning and push protection enabled. See SECURITY.md for vulnerability reporting.

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
• See THIRD_PARTY_NOTICES.md for third-party licenses

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