Teamcity

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.

[!NOTE]

Project status (October 2026): stable, low-key maintenance. This does what it set out to do and is no longer under active development. It still works and stays installable; issues and PRs may get slow or no response, and security fixes are best-effort.

JetBrains now ships official AI integration for TeamCity — an MCP server built into TeamCity 2026.1+ and the TeamCity CLI with an installable agent skill — which is the better default for most workflows. See _How this compares to JetBrains' official tooling_ below before adopting.

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

How this compares to JetBrains' official tooling

As of October 2026 (TeamCity 2026.2, TeamCity CLI 1.6), JetBrains ships two first-party paths for AI agents, both generally available and officially supported:

• Built-in MCP server — every TeamCity 2026.1+ server (Cloud and On-Premises) exposes an MCP endpoint at /app/mcp, so there's nothing to install. It's a deliberately small toolset: build logs, generic REST API GET/POST passthrough tools, and (since 2026.2) pipeline tools. By default it runs in a safe mode where the agent can read and queue personal builds; an opt-in "brave mode" lets it send arbitrary REST POST requests and edit or delete pipelines. Since 2026.2 you can also sign in with OAuth instead of pasting an access token.
• [TeamCity CLI](https://github.com/JetBrains/teamcity-cli) — an open-source teamcity command (TeamCity 2020.1+) with an installable agent skill (teamcity skill install) for Claude Code, Cursor, and other agents. It covers runs, logs, tests, the queue, agents, pools, projects, VCS roots, parameters, and pipelines, falls back to raw REST access via teamcity api, and has a read-only mode (TEAMCITY_RO=1). JetBrains' own docs describe it as the broader of the two options.

teamcity-mcp predates that tooling and overlaps with it heavily. The official tooling is the better default today. What teamcity-mcp still offers is narrower than it used to be:

• An MCP server for servers older than 2026.1. If your client speaks only MCP and your TeamCity server predates the built-in endpoint, this still works (TeamCity 2020.1+).
• Purpose-built MCP tools instead of a REST passthrough. It exposes 87 typed tools (gated by Dev/Full mode), so the agent doesn't need to know REST paths and locators — and it covers operations backed by PUT/DELETE (such as enabling agents or deleting parameters), which the built-in MCP's generic GET/POST tools don't reach.

JetBrains' tooling is evolving quickly, so rather than pin down a feature-by-feature comparison here (it would go stale fast), check the current docs and pick what fits:

• TeamCity 2026.2 announcement — pipeline tools, brave mode, and OAuth for the built-in MCP
• TeamCity 2026.1 announcement — where the official AI integration debuted
• AI agent integration docs — the built-in MCP, its tools, and safe vs. brave mode
• TeamCity CLI docs and agent skill — the terminal + agent-skill path

If you're comfortable with JetBrains' CLI, you may not need this project at all. It stays MIT-licensed and installable for whatever the built-ins don't yet reach — fork it if you want to take it further yourself.

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=" " \ 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_ " -- 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_ " --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=

TEAMCITY_HEADER_CF-Access-Client-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 impl