# TeamCity CI/CD

> TeamCity CI/CD is an open-source MCP server for developer tools. Read-only view of TeamCity builds, logs, failed tests, queue and agents. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows
- **Website:** https://blog.wentland.io/blog/read-only-mcp-server-teamcity/
- **Repository:** https://github.com/desty2k/readonly-mcp-teamcity
- **MCP Registry name:** io.github.desty2k/teamcity
- **Categories:** developer tools, cloud and infrastructure
- **Listing updated:** 2026-11-14

## About

Debugging a failed CI run usually means hopping between build pages. This server's diagnose_build tool answers why a build failed in one call, returning problems, failed tests (unmuted first) and the error lines of the log. Other tools search build history by config, branch, status or date, page through logs with tail and line-range support, and run full-text search inside a log.

It offers 29 tools covering projects, build configurations, builds, test results, problems, the queue, agents and VCS changes. A fuzzy find_build_config tool flags ambiguous matches, and get_build_chain shows snapshot dependencies upstream and downstream.

The server only issues GET requests, and every tool is annotated readOnlyHint. The README advises creating a token scoped per project with the Read-only preset so the token itself cannot change anything. It runs with uvx on Python 3.11 or newer.

## Features

- **One-call diagnosis:** diagnose_build gathers problems, failed tests and log errors.
- **Log search:** Paginate logs or search them with context.
- **Build history:** Filter builds by config, project, status, branch or date.
- **Config discovery:** Fuzzy find build configurations and read their steps and triggers.
- **Dependency chains:** See upstream and downstream snapshot dependencies.
- **Read-only by design:** Only GET requests; scoped read-only tokens recommended.

## Good for

- Find out why last night's build failed
- Search a log for an error message
- List which tests are failing and whether they are muted
- Look up which branches a configuration can build

## Install

### Claude Code (Terminal)

```sh
claude mcp add teamcity --env TEAMCITY_BASE_URL='<TEAMCITY_BASE_URL>' --env TEAMCITY_TOKEN='<TEAMCITY_TOKEN>' -- uvx readonly-mcp-teamcity
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": [
        "readonly-mcp-teamcity"
      ],
      "env": {
        "TEAMCITY_BASE_URL": "<TEAMCITY_BASE_URL>",
        "TEAMCITY_TOKEN": "<TEAMCITY_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": [
        "readonly-mcp-teamcity"
      ],
      "env": {
        "TEAMCITY_BASE_URL": "<TEAMCITY_BASE_URL>",
        "TEAMCITY_TOKEN": "<TEAMCITY_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "teamcity": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "readonly-mcp-teamcity"
      ],
      "env": {
        "TEAMCITY_BASE_URL": "<TEAMCITY_BASE_URL>",
        "TEAMCITY_TOKEN": "<TEAMCITY_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": [
        "readonly-mcp-teamcity"
      ],
      "env": {
        "TEAMCITY_BASE_URL": "<TEAMCITY_BASE_URL>",
        "TEAMCITY_TOKEN": "<TEAMCITY_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": [
        "readonly-mcp-teamcity"
      ],
      "env": {
        "TEAMCITY_BASE_URL": "<TEAMCITY_BASE_URL>",
        "TEAMCITY_TOKEN": "<TEAMCITY_TOKEN>"
      }
    }
  }
}
```

## Tools

- `search_projects`: Searches projects and browses the hierarchy.
- `get_project_details`: Returns a project's children, configs and parameters.
- `search_build_configs`: Searches build configurations.
- `find_build_config`: Fuzzy searches build configs.
- `get_build_config_details`: Returns steps, triggers, parameters and VCS roots.
- `get_build_config_branches`: Lists branches a config can build.
- `search_builds`: Searches build history.
- `get_build_details`: Returns one build's details.
- `get_build_statistics`: Returns durations, test counts and coverage.
- `get_build_chain`: Shows the snapshot-dependency chain.
- `get_build_log`: Pages through a build log.
- `search_build_log`: Full-text searches a build log.
- `diagnose_build`: Explains why a build failed.
- `get_build_test_results`: Lists test occurrences for a build.
- `get_test_details`: Returns one test's failure and history.

## FAQ

### Can it trigger or cancel builds?

No. It only issues GET requests and cannot trigger, cancel, pin, tag or modify anything.

### How do I authenticate?

Set TEAMCITY_BASE_URL and TEAMCITY_TOKEN; use a token limited per project with the Read-only preset.

### How many tools?

29, all reads.

### How do I run it?

With uvx, on Python 3.11 or newer.

### Is TeamCity CI/CD free?

Yes. TeamCity CI/CD is open source, so you can use and self-host it for free.

### How do I add TeamCity CI/CD to Claude Code?

Run this command in your terminal: claude mcp add teamcity --env TEAMCITY_BASE_URL='<TEAMCITY_BASE_URL>' --env TEAMCITY_TOKEN='<TEAMCITY_TOKEN>' -- uvx readonly-mcp-teamcity

### What are the best alternatives to TeamCity CI/CD?

The closest alternatives to TeamCity CI/CD are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/teamcity-ci-cd
