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
• AI Time Awareness: Provides real current date/time to prevent AI models from using training data dates

Environment Variables Reference

Required Variables

Authentication Variables