TeamCity MCP Server

1# TeamCity MCP Server
2 
3[![CI](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml)
4[![CodeQL](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml)
5[![codecov](https://codecov.io/gh/Daghis/teamcity-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/Daghis/teamcity-mcp)
6[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7 
8A Model Control Protocol (MCP) server that bridges AI coding assistants with JetBrains TeamCity CI/CD server, exposing TeamCity operations as MCP tools.
9 
10<a href="https://glama.ai/mcp/servers/@Daghis/teamcity-mcp">
11  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Daghis/teamcity-mcp/badge" alt="TeamCity Server MCP server" />
12</a>
13 
14## Overview
15 
16The 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.
17 
18> **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.
19 
20## Features
21 
22### 🚀 Two Operational Modes
23 
24- **Dev Mode** (default): Safe CI/CD operations (31 tools, ~14k context tokens)
25  - Trigger builds and monitor status
26  - Fetch build logs and inspect test failures
27  - List projects, configurations, and queue
28  - Read parameters and investigate problems
29 
30- **Full Mode**: Complete infrastructure management (87 tools, ~26k context tokens)
31  - All Dev mode features, plus:
32  - Create and clone build configurations
33  - Manage build steps, triggers, and dependencies
34  - Configure VCS roots and agents
35  - Full CRUD for parameters (build config, project, and output parameters)
36  - Queue management and server administration
37 
38**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.
39 
40See the [Tools Mode Matrix](docs/mcp-tools-mode-matrix.md) for the complete list of 87 tools and their availability by mode.
41 
42### 🎯 Key Capabilities
43 
44- Trigger and monitor builds, fetch logs, and inspect test failures
45- Token-based authentication to TeamCity; sensitive values redacted in logs
46- Modern architecture: simple, direct implementation with a singleton client
47- Performance-conscious: fast startup with minimal overhead
48- Clean codebase with clear module boundaries
49 
50## Installation
51 
52### Prerequisites
53 
54- Node.js >= 20.10.0 (LTS versions 20, 22, 24 tested in CI)
55- TeamCity Server 2020.1+ with REST API access
56- TeamCity authentication token
57 
58### Quick Start
59 
60```bash
61# Clone the repository
62git clone https://github.com/Daghis/teamcity-mcp.git
63cd teamcity-mcp
64 
65# Install dependencies
66npm install
67 
68# Configure environment
69cp .env.example .env
70# Edit .env with your TeamCity URL and token
71 
72# Run in development mode
73npm run dev
74```
75 
76### npm Package
77 
78Run the MCP server via npx (requires Node 20.x). Set your TeamCity environment variables inline or via a `.env` in the working directory.
79 
80```bash
81# One-off run (inline envs)
82TEAMCITY_URL="https://teamcity.example.com" \
83TEAMCITY_TOKEN="<your_token>" \
84MCP_MODE=dev \
85npx -y @daghis/teamcity-mcp
86 
87# Or rely on .env in the current directory
88npx -y @daghis/teamcity-mcp
89```
90 
91## Claude Code
92 
93- Add the MCP (relying on `.env` for configuration):
94  - `claude mcp add teamcity -- npx -y @daghis/teamcity-mcp`
95- With env vars (if not using .env):
96  - `claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp`
97- With CLI arguments (recommended for Windows):
98  - `claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev`
99- Add `-s user` to install user-wide instead of project-scoped (default)
100- Context usage (Opus 4.1, estimates):
101  - Dev (default): ~14k tokens for MCP tools
102  - Full (`MCP_MODE=full`): ~26k tokens for MCP tools
103 
104### Windows Users
105 
106On 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:
107 
108```json
109{
110  "mcpServers": {
111    "teamcity": {
112      "command": "npx",
113      "args": ["-y", "@daghis/teamcity-mcp", "--url", "https://teamcity.example.com", "--token", "YOUR_TOKEN"]
114    }
115  }
116}
117```
118 
119Or use a config file for better security (token not visible in process list):
120 
121```json
122{
123  "mcpServers": {
124    "teamcity": {
125      "command": "npx",
126      "args": ["-y", "@daghis/teamcity-mcp", "--config", "C:\\path\\to\\teamcity.env"]
127    }
128  }
129}
130```
131 
132## Configuration
133 
134Environment is validated centrally with Zod. Supported variables and defaults:
135 
136```env
137# Server Configuration
138PORT=3000
139NODE_ENV=development
140LOG_LEVEL=info
141 
142# TeamCity Configuration (aliases supported)
143TEAMCITY_URL=https://teamcity.example.com
144TEAMCITY_TOKEN=your-auth-token
145# Optional aliases:
146# TEAMCITY_SERVER_URL=...
147# TEAMCITY_API_TOKEN=...
148 
149# MCP Mode (dev or full)
150MCP_MODE=dev
151 
152# Optional advanced TeamCity options (defaults shown)
153# Connection
154# TEAMCITY_TIMEOUT=30000
155# TEAMCITY_MAX_CONCURRENT=10
156# TEAMCITY_KEEP_ALIVE=true
157# TEAMCITY_COMPRESSION=true
158 
159# Retry
160# TEAMCITY_RETRY_ENABLED=true
161# TEAMCITY_MAX_RETRIES=3
162# TEAMCITY_RETRY_DELAY=1000
163# TEAMCITY_MAX_RETRY_DELAY=30000
164 
165# Pagination
166# TEAMCITY_PAGE_SIZE=100
167# TEAMCITY_MAX_PAGE_SIZE=1000
168# TEAMCITY_AUTO_FETCH_ALL=false
169 
170# Circuit Breaker
171# TEAMCITY_CIRCUIT_BREAKER=true
172# TEAMCITY_CB_FAILURE_THRESHOLD=5
173# TEAMCITY_CB_RESET_TIMEOUT=60000
174# TEAMCITY_CB_SUCCESS_THRESHOLD=2
175```
176 
177These values are normalized in `src/config/index.ts` and consumed by `src/teamcity/config.ts` via helper getters.
178 
179## Usage Examples
180 
181Once integrated with your AI coding assistant:
182 
183```
184"Build the frontend on feature branch"
185"Why did last night's tests fail?"
186"Deploy staging with the latest build"
187"Create a new build config for the mobile app"
188```
189 
190### Tool Responses and Pagination
191 
192- Responses: Tools now return consistent MCP content. For list/get operations, the `content[0].text` contains a JSON string. Example shape:
193  `{ "items": [...], "pagination": { "page": 1, "pageSize": 100 } }` or `{ "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }`.
194- Pagination: Most list\_\* tools accept `pageSize`, `maxPages`, and `all`:
195  - `pageSize` controls items per page.
196  - `all: true` fetches multiple pages up to `maxPages`.
197  - Legacy `count` on `list_builds` is kept for compatibility but `pageSize` is preferred.
198 
199### Validation and Errors
200 
201- 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`.
202- 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.
203 
204### API Usage
205 
206```typescript
207import { TeamCityAPI } from '@/api-client';
208 
209// Get the API client instance
210const api = TeamCityAPI.getInstance();
211 
212// List projects
213const projects = await api.listProjects();
214 
215// Get build status
216const build = await api.getBuild('BuildId123');
217 
218// Trigger a new build
219const newBuild = await api.triggerBuild('BuildConfigId', {
220  branchName: 'main',
221});
222```
223 
224> **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.
225 
226## Development
227 
228```bash
229# Run tests
230npm test
231 
232# Run tests with coverage
233npm run test:coverage
234 
235# Lint code
236npm run lint
237 
238# Format code
239npm run format
240 
241# Type check
242npm run typecheck
243 
244# Build for production
245npm run build
246 
247# Analyze bundle for Codecov
248npm run build:bundle
249```
250 
251### Bundle analysis in CI
252 
253The CI workflow runs `npm run build:bundle` and uploads the generated `coverage/bundles` JSON using `codecov/codecov-action` with the `javascript-bundle` plugin.
254 
255## Project Structure
256 
257```
258teamcity-mcp/
259├── src/                    # Source code
260│   ├── tools.ts           # All 87 MCP tool definitions
261│   ├── server.ts          # MCP server setup
262│   ├── api-client.ts      # TeamCity API singleton
263│   ├── config/            # Configuration with Zod validation
264│   ├── teamcity/          # Domain logic (build, agent, config managers)
265│   ├── teamcity-client/   # Auto-generated OpenAPI client
266│   ├── types/             # TypeScript type definitions
267│   └── utils/             # Logger, MCP helpers, pagination
268├── tests/                  # Unit and integration tests
269├── docs/                   # Documentation
270└── scripts/                # Build and maintenance scripts
271```
272 
273## API Documentation
274 
275The MCP server exposes tools for TeamCity operations. Each tool corresponds to specific TeamCity REST API endpoints:
276 
277### Build Management
278 
279- `TriggerBuild` - Queue a new build
280- `GetBuildStatus` - Check build progress
281- `FetchBuildLog` - Retrieve build logs
282- `ListBuilds` - Search builds by criteria
283 
284### Test Analysis
285 
286- `ListTestFailures` - Get failing tests
287- `GetTestDetails` - Detailed test information
288- `AnalyzeBuildProblems` - Identify failure reasons
289 
290### Configuration (Full Mode Only)
291 
292- `create_build_config` - Create new TeamCity build configurations with full support for:
293  - VCS roots (Git, SVN, Perforce) with authentication
294  - Build steps (script, Maven, Gradle, npm, Docker, PowerShell)
295  - Triggers (VCS, schedule, finish-build, maven-snapshot)
296  - Parameters and template-based configurations
297  - See the [MCP Tool Reference](docs/mcp-tools-reference.md) for argument details and additional options.
298- `clone_build_config` - Duplicate existing configurations into any project, preserving steps, triggers, and parameters.
299- `update_build_config` - Adjust names, descriptions, artifact rules, and pause state for a configuration.
300- `manage_build_steps` - Add, update, remove, or reorder build steps through a single tool surface.
301- `manage_build_triggers` - Add or delete build triggers with full property support.
302- `create_vcs_root` & `add_vcs_root_to_build` - Define VCS roots and attach them to build configurations.
303 
304See also: [`docs/TEAMCITY_MCP_TOOLS_GUIDE.md`](docs/TEAMCITY_MCP_TOOLS_GUIDE.md) for expanded workflows and examples that align with the current MCP implementation.
305 
306## Contributing
307 
308We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
309 
310## Security
311 
312### Token Management
313 
314- Configure `TEAMCITY_TOKEN` via environment variable or config file (see `.env.example`); never commit real tokens
315- Use a token with minimal required permissions; read-only tokens work for most Dev mode operations
316- Token-based authentication only; the MCP server does not support username/password
317- Logs redact sensitive values including tokens
318 
319### Mode Selection
320 
321- Prefer **Dev mode** unless Full mode is explicitly needed—this limits the blast radius of any misconfiguration or prompt injection
322- Full mode enables destructive operations (project deletion, agent management) that cannot be easily undone
323 
324### Network Security
325 
326- Always use HTTPS for TeamCity connections; the server does not enforce this but strongly recommends it
327- The MCP server connects only to the configured TeamCity URL; no other network calls are made
328 
329### AI Assistant Considerations
330 
331- AI assistants could be manipulated via prompt injection in build logs, test output, or other TeamCity data
332- Dev mode's limited tool set reduces the impact of such attacks
333- All actions appear in TeamCity's audit log under the token's associated user
334- Build logs and test failure details may contain sensitive information (secrets, paths, internal URLs) that become visible to the AI assistant
335 
336### Repository Security
337 
338This repository has GitHub secret scanning and push protection enabled. See [SECURITY.md](SECURITY.md) for vulnerability reporting.
339 
340## Support
341 
342- GitHub Issues: [Report bugs or request features](https://github.com/Daghis/teamcity-mcp/issues)
343- Documentation: See the `docs/` folder in this repository
344 
345## Acknowledgments
346 
347- JetBrains TeamCity for the excellent CI/CD platform
348- Anthropic for the Model Control Protocol specification
349- The open-source community for continuous support
350- See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for third-party licenses
351 
352---
353 
354Built with ❤️ for developers who love efficient CI/CD workflows