TeamCity MCP server for AI agents

The TeamCity MCP server provides a bridge between JetBrains TeamCity and AI-powered IDEs, exposing TeamCity resources and tools in a structured format that LLM agents and IDE plugins can interact with through the Model Context Protocol (MCP).

Installation

Docker Installation (Recommended)

The simplest way to run the TeamCity MCP server is using Docker:

docker run -p 8123:8123 \
  -e TC_URL=https://your-teamcity-server.com \
  -e TC_TOKEN=your-teamcity-api-token \
  -e SERVER_SECRET=your-hmac-secret-key \
  itcaat/teamcity-mcp:latest

Local Binary Installation

To build and run the server locally:

# Build the server
make build
# This creates ./bin/teamcity-mcp and a symlink ./server

# Set required environment variables
export TC_URL="https://your-teamcity-server.com"
export TC_TOKEN="your-teamcity-api-token"
export SERVER_SECRET="your-hmac-secret-key"  # Optional for HMAC authentication

# Run the server
./server
# Server starts on :8123 by default

Configuration

Environment Variables

Required Variables

Variable	Description	Example
`TC_URL`	TeamCity server URL	`https://teamcity.company.com`
`TC_TOKEN`	TeamCity API token	`eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...`

Optional Variables

Variable	Default	Description	Example
`SERVER_SECRET`		HMAC secret for client authentication	`my-secure-secret-123`
`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

IDE Integration

Cursor Integration

Add this configuration 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"
        }
      }
    }
}

If you prefer to use a 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"
    }
  }
}

Docker Deployment

Build and Run Docker

# Pull the image
docker pull itcaat/teamcity-mcp:latest

# 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 \
  itcaat/teamcity-mcp:latest

Docker Compose

# Start with docker-compose
docker-compose up -d

# Check logs
docker-compose logs -f teamcity-mcp

Command Line Options

Flag	Description	Default
`--help`	Show environment variable help
`--version`	Show version information
`--transport`	Transport mode: http or stdio	`http`

Available Tools

The server provides 6 powerful tools for managing TeamCity builds:

1. trigger_build

Trigger a new build in TeamCity.

Parameters:

buildTypeId (required): Build configuration ID
branchName (optional): Branch name to build
properties (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 cancel
comment (optional): Cancellation comment

3. pin_build

Pin or unpin a build to prevent it from being cleaned up.

Parameters:

buildId (required): Build ID to pin/unpin
pin (required): true to pin, false to unpin
comment (optional): Pin comment

4. set_build_tag

Add or remove tags from a build.

Parameters:

buildId (required): Build ID
tags (optional): Array of tags to add
removeTags (optional): Array of tags to remove

5. download_artifact

Download build artifacts.

Parameters:

buildId (required): Build ID
artifactPath (required): Path to the artifact

6. search_builds

Search for builds with comprehensive filtering options.

Parameters (all optional):

buildTypeId: Filter by build configuration ID
status: Filter by build status (SUCCESS, FAILURE, ERROR, UNKNOWN)
state: Filter by build state (queued, running, finished)
branch: Filter by branch name
agent: Filter by agent name
user: Filter by user who triggered the build
tags: Array of tags to filter by
count: Maximum number of builds to return (1-1000, default: 100)

Testing and Verification

Quick Health Check

# 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":{}}}'

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
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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect