teamcity-mcp

# TeamCity MCP Server

[![CI](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml)
[![codecov](https://codecov.io/gh/Daghis/teamcity-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/Daghis/teamcity-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

<a href="https://glama.ai/mcp/servers/@Daghis/teamcity-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Daghis/teamcity-mcp/badge" alt="TeamCity Server MCP server" />
</a>

> [!NOTE]
> **Project status (June 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 — a built-in MCP and the [TeamCity CLI](https://github.com/JetBrains/teamcity-cli) with an installable agent skill — which is the better default for most workflows. See [_How this compares to JetBrains' official tooling_](#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](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](docs/mcp-tools-mode-matrix.md) 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 June 2026,** JetBrains ships first-party AI integration for TeamCity: a built-in MCP endpoint and the [TeamCity CLI](https://github.com/JetBrains/teamcity-cli), which includes an installable agent skill. Together these are JetBrains' recommended path and cover the common AI workflows — reading logs, diagnosing failures, and rerunning builds — with no install and official support.

teamcity-mcp predates that tooling and overlaps with it. Broadly, the official tooling is the better default today; teamcity-mcp's remaining edge is a broader set of write and management operations exposed as an MCP server. That gap is real but narrowing, and 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.1 announcement](https://blog.jetbrains.com/teamcity/2026/05/teamcity-20261/) — overview of the official AI integration
- [AI agent integration docs](https://www.jetbrains.com/help/teamcity/ai-agent-integration.html) — the built-in MCP
- [TeamCity CLI](https://github.com/JetBrains/teamcity-cli) — 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

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

```bash
# 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](https://github.com/anthropics/claude-code/issues/1254). Use CLI arguments as a workaround:

```json
{
  "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):

```json
{
  "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:

```env
# 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

```typescript
import { TeamCityAPI } from '@/api-client';

// Get the API client instance
con