itcaat/teamcity-mcp
If you are the rightful owner of teamcity-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The TeamCity MCP Server is a comprehensive Model Context Protocol server that integrates JetBrains TeamCity with AI-ready resources and tools for LLM agents and IDE plugins.
TeamCity MCP Server
A comprehensive Model Context Protocol (MCP) server that exposes JetBrains TeamCity as structured AI-ready resources and tools for LLM agents and IDE plugins.
Quick Start
IDE Integration (Cursor)
The TeamCity MCP server is designed to work seamlessly with AI-powered IDEs like Cursor. Here's how to configure it:
Cursor Configuration
Add this to your Cursor MCP settings:
{
"mcpServers": {
"teamcity": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"TC_URL",
"-e",
"TC_TOKEN",
"itcaat/teamcity-mcp:latest",
"--transport",
"stdio"
],
"env": {
"TC_URL": "https://your-teamcity-server.com",
"TC_TOKEN": "your-teamcity-api-token"
}
}
}
}
Local Development
1. Build the Server
make build
# This creates ./bin/teamcity-mcp and a symlink ./server
2. Set Environment Variables
# Required
export TC_URL="https://your-teamcity-server.com"
# Optional (enables HMAC authentication)
export SERVER_SECRET="your-hmac-secret-key"
# Authentication
export TC_TOKEN="your-teamcity-api-token"
3. Run the Server
./server
# Server starts on :8123 by default
4. Test the Server
# Health check
curl http://localhost:8123/healthz
# MCP protocol test
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-hmac-secret-key" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'
Expected result: Health endpoint should return {"status":"ok"}
and MCP endpoint should return initialization response.
Features
- MCP Protocol Compliance: Full JSON-RPC 2.0 over HTTP/WebSocket support
- TeamCity Integration: Complete REST API integration with authentication
- Resource Access: Projects, build types, builds, agents, and artifacts
- Build Operations: Trigger, cancel, pin builds, set tags, download artifacts, search builds
- Advanced Search: Comprehensive build search with multiple filters (status, branch, user, dates, tags)
- Production Ready: Docker, Kubernetes, monitoring, caching, and comprehensive logging
- Environment-Based Configuration: No config files needed, everything via environment variables
Environment Variables Reference
Required Variables
Variable | Description | Example |
---|---|---|
TC_URL | TeamCity server URL | https://teamcity.company.com |
SERVER_SECRET | HMAC secret for client authentication (optional) | my-secure-secret-123 |
Authentication Variables
Variable | Description | Example |
---|---|---|
TC_TOKEN | TeamCity API token | eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... |
Optional Variables
Variable | Default | Description | Example |
---|---|---|---|
LISTEN_ADDR | :8123 | Server listen address | :8080 or 0.0.0.0:8123 |
TC_TIMEOUT | 30s | TeamCity API timeout | 60s or 2m |
TLS_CERT | Path to TLS certificate | /path/to/cert.pem | |
TLS_KEY | Path to TLS private key | /path/to/key.pem | |
LOG_LEVEL | info | Log level | debug , info , warn , error |
LOG_FORMAT | json | Log format | json or console |
CACHE_TTL | 10s | Cache TTL for API responses | 30s or 1m |
Configuration Examples
Development Environment
export TC_URL=http://localhost:8111
export TC_TOKEN=dev-token-123
export SERVER_SECRET=dev-secret
export LOG_LEVEL=debug
export LOG_FORMAT=console
./server
Production Environment
export TC_URL=https://teamcity.company.com
export TC_TOKEN=$TEAMCITY_API_TOKEN
export SERVER_SECRET=$MCP_SERVER_SECRET
export TLS_CERT=/etc/ssl/certs/teamcity-mcp.pem
export TLS_KEY=/etc/ssl/private/teamcity-mcp.key
export LOG_LEVEL=warn
export CACHE_TTL=30s
./server
Docker Deployment
Build and Run
# Build Docker image
make docker
# Run with environment variables
docker run -p 8123:8123 \
-e TC_URL=https://teamcity.company.com \
-e TC_TOKEN=your-token \
-e SERVER_SECRET=your-secret \
teamcity-mcp:latest
Docker Compose
# Start with docker-compose
docker-compose up -d
# Check logs
docker-compose logs -f teamcity-mcp
Kubernetes Deployment
Using Helm
# Deploy with Helm
helm install teamcity-mcp ./helm/teamcity-mcp \
--set teamcity.url=https://teamcity.company.com \
--set secrets.teamcityToken=your-token \
--set secrets.serverSecret=your-secret
Manual Kubernetes Deployment
apiVersion: v1
kind: Secret
metadata:
name: teamcity-mcp-secrets
type: Opaque
stringData:
teamcity-token: "your-teamcity-token"
server-secret: "your-server-secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: teamcity-mcp
spec:
replicas: 1
selector:
matchLabels:
app: teamcity-mcp
template:
metadata:
labels:
app: teamcity-mcp
spec:
containers:
- name: teamcity-mcp
image: teamcity-mcp:latest
ports:
- containerPort: 8123
env:
- name: TC_URL
value: "https://teamcity.company.com"
- name: TC_TOKEN
valueFrom:
secretKeyRef:
name: teamcity-mcp-secrets
key: teamcity-token
- name: SERVER_SECRET
valueFrom:
secretKeyRef:
name: teamcity-mcp-secrets
key: server-secret
Command Line Options
Flag | Description | Default |
---|---|---|
--help | Show environment variable help | |
--version | Show version information | |
--transport | Transport mode: http or stdio | http |
Help and Documentation
# Show environment variable help
./server --help
# Show version
./server --version
# Show command line usage
./server -h
Testing and Verification
Automated Verification
Use the included verification script to test all functionality:
# Run all tests
./scripts/verify.sh
# Available options:
./scripts/verify.sh help # Show help
./scripts/verify.sh start # Start server only
./scripts/verify.sh stop # Stop server only
./scripts/verify.sh clean # Clean up processes
Manual Testing
# 1. Set environment variables
export TC_URL=http://localhost:8111
export TC_TOKEN=test-token
export SERVER_SECRET=test-secret
# 2. Start server
./server &
# 3. Test health
curl http://localhost:8123/healthz
# 4. Test MCP protocol
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer test-secret" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'
# 5. Stop server
pkill -f teamcity-mcp
Development Testing
# Install dependencies
make deps
# Run unit tests
make test
# Run integration tests
make test-integration
# Run load tests
make test-load
# Run linter
make lint
# Format code
make format
# Clean build artifacts
make clean
Available Make Commands
Use make help
to see all available commands:
# Basic commands
make build # Build the binary
make test # Run tests
make clean # Clean build artifacts
make deps # Download dependencies
make lint # Run linters
make format # Format code
# Docker commands
make docker # Build Docker image
make docker-push # Push Docker image
# Running commands
make run # Run the application
make run-stdio # Run in STDIO mode
make dev # Run in development mode with hot reload
# Docker Compose commands
make compose-up # Start services with Docker Compose
make compose-down # Stop services
make compose-logs # Show logs
# Testing commands
make test-integration # Run integration tests with Docker
make test-load # Run load tests
# Development tools
make install-tools # Install development tools
# Release commands
make release-snapshot # Build snapshot release with GoReleaser
make release-check # Check GoReleaser configuration
# CI commands
make ci # Run CI checks (deps, lint, test, build)
make check # Run all checks (lint, test, build)
MCP Protocol Testing
Initialize MCP Session
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {
"name": "test-client",
"version": "1.0.0"
}
}
}'
List Resources
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/list",
"params": {}
}'
List Tools
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/list",
"params": {}
}'
Available Tools
The TeamCity MCP server provides 6 powerful tools for managing builds:
1. trigger_build
Trigger a new build in TeamCity.
Parameters:
buildTypeId
(required): Build configuration IDbranchName
(optional): Branch name to buildproperties
(optional): Build properties object
Example:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "trigger_build",
"arguments": {
"buildTypeId": "YourProject_BuildConfiguration",
"branchName": "main",
"properties": {
"env.DEPLOY_ENV": "staging"
}
}
}
}'
2. cancel_build
Cancel a running build.
Parameters:
buildId
(required): Build ID to cancelcomment
(optional): Cancellation comment
Example:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "cancel_build",
"arguments": {
"buildId": "12345",
"comment": "Cancelled due to urgent hotfix"
}
}
}'
3. pin_build
Pin or unpin a build to prevent it from being cleaned up.
Parameters:
buildId
(required): Build ID to pin/unpinpin
(required): true to pin, false to unpincomment
(optional): Pin comment
Example:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "pin_build",
"arguments": {
"buildId": "12345",
"pin": true,
"comment": "Release candidate build"
}
}
}'
4. set_build_tag
Add or remove tags from a build.
Parameters:
buildId
(required): Build IDtags
(optional): Array of tags to addremoveTags
(optional): Array of tags to remove
Example:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "set_build_tag",
"arguments": {
"buildId": "12345",
"tags": ["release", "v1.2.3"],
"removeTags": ["beta"]
}
}
}'
5. download_artifact
Download build artifacts.
Parameters:
buildId
(required): Build IDartifactPath
(required): Path to the artifact
Example:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "download_artifact",
"arguments": {
"buildId": "12345",
"artifactPath": "dist/app.zip"
}
}
}'
6. search_builds
Search for builds with comprehensive filtering options.
Parameters (all optional):
buildTypeId
: Filter by build configuration IDstatus
: Filter by build status (SUCCESS, FAILURE, ERROR, UNKNOWN)state
: Filter by build state (queued, running, finished)branch
: Filter by branch nameagent
: Filter by agent nameuser
: Filter by user who triggered the buildsinceBuild
: Search builds since this build IDsinceDate
: Search builds since this date (YYYYMMDDTHHMMSS+HHMM)untilDate
: Search builds until this date (YYYYMMDDTHHMMSS+HHMM)tags
: Array of tags to filter bypersonal
: Include personal builds (boolean)pinned
: Filter by pinned status (boolean)count
: Maximum number of builds to return (1-1000, default: 100)
Examples:
Search for failed builds:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "search_builds",
"arguments": {
"status": "FAILURE",
"count": 10
}
}
}'
Search for recent builds on main branch:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 10,
"method": "tools/call",
"params": {
"name": "search_builds",
"arguments": {
"branch": "main",
"state": "finished",
"count": 20
}
}
}'
Search for builds with specific tags:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 11,
"method": "tools/call",
"params": {
"name": "search_builds",
"arguments": {
"tags": ["release", "production"],
"pinned": true
}
}
}'
Local Binary Configuration
If you prefer to use the local binary instead of Docker:
{
"teamcity": {
"command": "/path/to/teamcity-mcp",
"args": ["--transport", "stdio"],
"env": {
"TC_URL": "https://your-teamcity-server.com",
"TC_TOKEN": "your-teamcity-api-token"
}
}
}
Usage in Cursor
Once configured, you can use natural language commands like:
- "Search for failed builds in the last week"
- "Trigger a build for the main branch"
- "Show me recent builds for project X"
- "Pin the latest successful build"
- "Cancel the running build 12345"
- "Add a release tag to build 12345"
The AI will automatically use the appropriate TeamCity tools to fulfill your requests.
Available Resources
The server exposes TeamCity data as MCP resources:
teamcity://projects
- List all projectsteamcity://buildTypes
- List all build configurationsteamcity://builds
- List recent buildsteamcity://agents
- List build agents
Troubleshooting
Common Issues
-
Missing required environment variables
Error: TC_URL environment variable is required
Solution: Set all required environment variables
-
Authentication failures
Error: TC_TOKEN environment variable is required
Solution: Set
TC_TOKEN
with your TeamCity API token -
Invalid timeout format
Error: invalid TC_TIMEOUT format
Solution: Use valid duration format like
30s
,1m
,2h
-
Port already in use
Error: listen tcp :8123: bind: address already in use
Solution: Set
LISTEN_ADDR
to a different port or stop the conflicting service
Debug Mode
Enable debug logging:
export LOG_LEVEL=debug
export LOG_FORMAT=console
./server
Health Check
The server provides a health endpoint:
curl http://localhost:8123/healthz
# Expected: {"service":"teamcity-mcp","status":"ok","timestamp":"..."}
Metrics
Prometheus metrics are available:
curl http://localhost:8123/metrics
TeamCity Integration Testing
Verify TeamCity connectivity:
# Check TeamCity server accessibility
curl -H "Authorization: Bearer your-token" \
http://your-teamcity-url/app/rest/projects
# Verify authentication
curl -H "Authorization: Bearer your-token" \
http://your-teamcity-url/app/rest/server
Protocol Reference
See for detailed MCP protocol implementation and TeamCity API mapping.
License
MIT License - see for details.