readonly-mcp-teamcity

A read-only Model Context Protocol (MCP) server that lets AI agents explore a JetBrains TeamCity server: projects, build configurations, builds, logs, test results, problems, the queue, agents, and VCS changes. 29 tools, all of them reads.

Quick start

With uv installed, there is nothing else to install:

claude mcp add teamcity \
  -e TEAMCITY_BASE_URL=https://teamcity.example.com \
  -e TEAMCITY_TOKEN=your-token \
  -- uvx readonly-mcp-teamcity

uvx downloads the package into a cached, isolated environment and runs it. Python 3.11 or newer.

Read-only by design. This server only ever issues GET requests (a test fails if the HTTP client gains any other method). It cannot trigger, cancel, pin, tag, or modify anything in TeamCity, and every tool is annotated readOnlyHint. Scope the token read-only on the TeamCity side as a second line of defense: see Token. Read the post about this server and why I build read-only MCP servers.

Token

Create a token under Profile → Access Tokens. Set Permissions scope to Limit per project, pick the root project (or the projects the agent should see), and choose the Read-only preset. A token scoped that way cannot change anything even if a client misbehaves.

The Read-only preset selects the 14 VIEW_* permissions TeamCity marks as read-only, including global ones for agent details and server settings. A token never gets more than its owner has: with a token from a user who has only the Project viewer role, agent tools still work, and get_server_health reports metrics as unavailable but still returns health items. Checked against TeamCity 2026.2.1, where a preset token could not pin a build (HTTP 403).

Tools

Projects

Build configurations

Builds

Logs

Tests & problems

Infrastructure

Install

Run it without installing (recommended):

uvx readonly-mcp-teamcity

Or install it into an environment:

uv tool install readonly-mcp-teamcity   # or: pip install readonly-mcp-teamcity

Docker

The image serves the streamable HTTP transport on port 8080. That transport has no authentication, so publish it on the host's loopback only:

docker run --rm \
  -e TEAMCITY_BASE_URL=https://teamcity.example.com \
  -e TEAMCITY_TOKEN=your-token \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/desty2k/readonly-mcp-teamcity:latest

Configuration

All configuration comes from TEAMCITY_* environment variables.

See .env.example for a copy-paste template.

OpenTelemetry tracing

Tracing is opt-in and a no-op when disabled. The base install carries no OTel SDK; install the extra and enable it to export spans for each upstream TeamCity call:

pip install 'readonly-mcp-teamcity[otel]'
export TEAMCITY_OTEL_ENABLED=true
export TEAMCITY_OTEL_ENDPOINT=http://localhost:4317   # optional; falls back to OTEL_EXPORTER_OTLP_ENDPOINT

MCP client configuration

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": ["readonly-mcp-teamcity"],
      "env": {
        "TEAMCITY_BASE_URL": "https://teamcity.example.com",
        "TEAMCITY_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

See Quick start.

How it compares

As of November 2026. Check the projects themselves before relying on this.

Sources: JetBrains AI agent integration, JetBrains/teamcity-mcp, Daghis/teamcity-mcp, itcaat/teamcity-mcp, kate-horshchar/teamcity-qa-mcp. The JetBrains plugin README and its help page disagree on whether brave mode is on by default; check your server's setting.

Use the built-in server if you want an agent to act on TeamCity. Use this one when the agent should only look.

Example questions

• "Find the deploy pipeline for the auth service."
• "Show me the last 10 builds for Proj_Build and which failed."
• "Why did build 12345 fail?" (one diagnose_build call)
• "What tests failed in that build, and what was the error?"
• "Search the build log for OutOfMemoryError."
• "Which agents are offline right now?"
• "What's in the build queue and why is it waiting?"
• "Who is investigating the failures in the Payments project?"
• "What commits went into this build?"
• "Resolve https://teamcity.example.com/buildConfiguration/Proj_Build/12345."

Development

git clone https://github.com/desty2k/readonly-mcp-teamcity
cd readonly-mcp-teamcity
uv sync --all-extras
uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

A live smoke test against a real server (reads credentials from .env):

uv run python tests/smoke_test.py

License

MIT — see LICENSE.