home / mcp / teamcity mcp server

TeamCity MCP Server

Teamcity MCP Server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "itcaat-teamcity-mcp": {
      "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",
        "SERVER_SECRET": "my-secure-secret-123"
      }
    }
  }
}

You run a TeamCity MCP Server to expose TeamCity resources and actions as structured, AI-ready endpoints. This lets AI agents and IDE plugins discover projects, builds, and artifacts, and perform operations like triggering builds or fetching logs through a consistent MCP interface.

How to use

You interact with the TeamCity MCP Server by connecting an MCP client that supports JSON-RPC 2.0 over HTTP or via stdio transport. Through the MCP interface, you can list resources such as projects, build configurations, builds, and agents; trigger builds; fetch logs and artifacts; search and filter builds; and retrieve metadata about current time and test results. Use the client to initialize a session, explore available resources, and call tools to perform actions against TeamCity. The server handles authentication via a TeamCity API token and can optionally enable HMAC-based client authentication.

How to install

Prerequisites: you need a machine with Docker installed and access to your TeamCity instance. If you prefer running a local binary, you can start from a prebuilt MCP binary that supports stdio transport. The setup options include running via Docker or using a local binary with the stdio transport. Follow the concrete steps below to choose your preferred method and start the MCP server.

# 1) Run via Docker (recommended for quick start)
# This pulls the MCP image and runs it with stdio transport
# You will supply your TeamCity URL and API token via environment variables

Configuration and security

Set these environment variables to configure the MCP server and authenticate to TeamCity. You can provide the necessary variables for each running method. Optional security can include an HMAC secret for client authentication.

# 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"
```

```bash
# Optional TLS configuration (when using a local binary)
export TLS_CERT="/path/to/cert.pem"
export TLS_KEY="/path/to/key.pem"

Troubleshooting and tips

If you encounter issues, verify that all required environment variables are set, the MCP transport is correctly configured, and the TeamCity API token has the necessary permissions. Check the health endpoint to confirm the server is responsive and inspect logs for errors related to authentication, timeouts, or network access.

Tools and endpoints overview

The TeamCity MCP Server exposes a set of tools that enable common TeamCity operations via MCP. You can trigger builds, cancel running ones, pin builds, manage tags, download artifacts, and perform advanced searches across builds and configurations. You can also fetch build logs with filtering options, query current time on the server, and retrieve test results for specific builds.

Security notes

Keep your TeamCity API token secret secure. Use the optional SERVER_SECRET for additional client authentication as needed. Rotate tokens regularly and follow your organization’s security policies for secret management.

Examples and usage scenarios

Typical workflows include initializing a session, listing recent builds, triggering a build for a specific configuration, fetching logs for analysis, and identifying configurations that match specific criteria. You can combine resource queries with tool calls to automate CI workflows and create concise, AI-readable summaries of build activity.

Available tools

trigger_build

Trigger a new build for a given build configuration. Provide the buildTypeId, optional branch, and optional properties for the build.

cancel_build

Cancel a running build by its ID with an optional cancellation comment.

pin_build

Pin or unpin a build to prevent it from being cleaned up. Specify buildId, pin, and optional comment.

set_build_tag

Add or remove tags from a build by providing buildId and tag lists.

download_artifact

Download a build artifact by specifying the buildId and artifactPath.

search_builds

Search builds with comprehensive filters including status, branch, user, dates, tags, and more.

fetch_build_log

Fetch the build log with options for formatting, filtering, and tailing.

search_build_configurations

Search build configurations with basic and advanced filters, including parameters, steps, and VCS details.

get_current_time

Return the current server date and time in a specified format and timezone to ensure AI models use real time.

get_test_results

Retrieve test results for a given build with optional status filtering and detail options.