TeamCity MCP Server
About
MCP server for JetBrains TeamCity with 87 tools for builds, tests, agents, and CI/CD pipeline management.
Details
- Author
- daghis
- Categories
- Developer Tools, Infrastructure
Jump to
Setup
Install TeamCity MCP Server in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/daghis/teamcity-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
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 (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 theTeamCity CLIwith an installable agent skill — which is the better default for most workflows. SeeHow this compares to JetBrains' official toolingbelow before adopting.
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 toMCP_MODE=fullor use runtime mode switching (v2.1.0+). SeeCHANGELOG.mdfor details.
-
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 theget_mcp_modeandset_mcp_modetools—no restart required. MCP clients that support notifications will see the tool list update automatically.
See theTools Mode Matrixfor the complete list of 87 tools and their availability by mode.
- 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 theTeamCity 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— overview of the official AI integration
- AI agent integration docs— the built-in MCP
- 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.
- Node.js >= 20.10.0 (LTS versions 20, 22, 24 tested in CI)
- TeamCity Server 2020.1+ with REST API access
- TeamCity authentication token
# 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
Run the MCP server via npx (requires Node 20.x). Set your TeamCity environment variables inline or via a.envin 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
- Add the MCP (relying on.envfor configuration):
- claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
- claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp
- claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev
- Dev (default): ~14k tokens for MCP tools
- Full (MCP_MODE=full): ~26k tokens for MCP tools
On Windows, Claude Code's MCP configurationmay 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"] } } }
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 insrc/config/index.tsand consumed bysrc/teamcity/config.tsvia helper getters.
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"
- Responses: Tools now return consistent MCP content. For list/get operations, thecontent[0].textcontains a JSON string. Example shape:{ "items": [...], "pagination": { "page": 1, "pageSize": 100 } }or{ "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }.
- Pagination: Most list_* tools acceptpageSize,maxPages, andall:
- pageSizecontrols items per page.
- all: truefetches multiple pages up tomaxPages.
- Legacycountonlist_buildsis kept for compatibility butpageSizeis preferred.
- Input validation: Tool inputs are validated with Zod schemas; invalid input returns a structured error payload in the response content (JSON string) withsuccess: falseanderror.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.
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 fromsrc/teamcity/index.tsremain only for compatibility and include placeholder implementations. Prefer the MCP tools (see the reference linked above) or theTeamCityAPIshown here when automating workflows.
# 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
The CI workflow runsnpm run build:bundleand uploads the generatedcoverage/bundlesJSON usingcodecov/codecov-actionwith thejavascript-bundleplugin.
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
The MCP server exposes tools for TeamCity operations. Each tool corresponds to specific TeamCity REST API endpoints:
- TriggerBuild- Queue a new build
- GetBuildStatus- Check build progress
- FetchBuildLog- Retrieve build logs
- ListBuilds- Search builds by criteria
- ListTestFailures- Get failing tests
- GetTestDetails- Detailed test information
- AnalyzeBuildProblems- Identify failure reasons
- 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 theMCP Tool Referencefor argument details and additional options.
We welcome contributions! Please seeCONTRIBUTING.mdfor details.
- ConfigureTEAMCITY_TOKENvia 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
- PreferDev modeunless 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
- 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 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
This repository has GitHub secret scanning and push protection enabled. SeeSECURITY.mdfor vulnerability reporting.
- GitHub Issues:Report bugs or request features
- Documentation: See thedocs/folder in this repository
- JetBrains TeamCity for the excellent CI/CD platform
- Anthropic for the Model Control Protocol specification
- The open-source community for continuous support
- SeeTHIRD_PARTY_NOTICES.mdfor third-party licenses
Built with ❤️ for developers who love efficient CI/CD workflows
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
The Shipyard CLI provides an MCP server for agents to manage Shipyard environments directly: by pulling logs, comparing branches, running tests, and stopping/starting environments..
Open-source CLI for testing MCP servers and detecting schema drift
Check if a command is runnable before running it.
MCP server that generates production-grade engineering standards (SOLID, testing, architecture, CI/CD) for AI coding assistants
Read-first Jenkins MCP server in Go for agent-driven build debugging. 20 tools including compare_builds, flaky-test detection, JUnit/Ginkgo failure parsing, and disk-cached console logs with on-disk path handoff. Write tools (trigger/stop/cancel) gated by JENKINS_MCP_READONLY env var.
A comprehensive toolkit for developing, testing, and deploying Model Context Protocol (MCP) servers.
An MCP server for Nextflow development and testing, which requires a local clone of the Nextflow Git repository.
MCP server for safe AI agent runtime upgrades — version-aware regression catalog, pre/post snapshot diffing, rollback guides. v1.2 added provider-fingerprint detection for silent provider-side regressions.
Provides isolated Docker environments for secure code execution.
The Superserve MCP server lets any MCP client create and control isolated cloud sandboxes
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
