TeamCity MCP Server

# TeamCity MCP Server [](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml) [](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml) [](https://codecov.io/gh/Daghis/teamcity-mcp) [](LICENSE) 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. ## Features ### 🚀 Two Operational Modes - **Dev Mode**: Safe CI/CD operations - Trigger builds - Monitor build status and progress - Fetch build logs - Investigate test failures - List projects and configurations - **Full Mode**: Complete infrastructure management - All Dev mode features, plus: - Create and clone build configurations - Manage build steps and triggers - Configure VCS roots and agents - Set up new projects - Modify infrastructure settings ### 🎯 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 ## Installation ### Prerequisites - Node.js >= 20.10.0 - 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: - `claude mcp add [-s user] teamcity -- npx -y @daghis/teamcity-mcp` - With env vars (if not using .env): - `claude mcp add [-s user] teamcity -- env TEAMCITY_URL="https://teamcity.example.com" TEAMCITY_TOKEN="tc_<your_token>" MCP_MODE=dev npx -y @daghis/teamcity-mcp` - Context usage (Opus 4.1, estimates): - Dev (default): ~14k tokens for MCP tools - Full (`MCP_MODE=full`): ~26k tokens for MCP tools ## 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 # 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 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 ```bash # 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/ # MCP tool implementations │ ├── utils/ # Utility functions │ ├── types/ # TypeScript type definitions │ └── config/ # Configuration management ├── tests/ # Test files ├── docs/ # Documentation └── .agent-os/ # Agent OS specifications ``` ## 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](docs/mcp-tools-reference.md) 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`](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](CONTRIBUTING.md) for details. ## Security - Configure `TEAMCITY_TOKEN` via environment (see `.env.example`); never commit real tokens - Token-based authentication only - Logs redact sensitive values ## Support - GitHub Issues: [Report bugs or request features](https://github.com/Daghis/teamcity-mcp/issues) - 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 --- Built with ❤️ for developers who love efficient CI/CD workflows