peakflames/teamcity-remote-mcp-server repository overview

⁠TeamCity MCP Servers

This repository contains Model Context Protocol (MCP) server implementations for TeamCity CI/CD integration.

⁠Available MCP Tools

The server exposes the following tools for navigating TeamCity projects, inspecting build configurations, and querying build state.

⁠Project & Build Configuration Tools

⁠Build Tools

⁠Projects

• TeamCityRemoteMcpServer: ASP.NET Web API-based MCP server for server-based installations (Streamable HTTP transport, stateless; optional OAuth 2.1 authentication and per-caller RBAC)
• TeamCityMcpServer: Console-based MCP server for local workstation installations (stdio transport)

⁠Running via Docker & Linux Server (Recommended)

1. From your Linux server, create a directory for your configuration:

   mkdir -p /opt/teamcity-mcp-server
   cd /opt/teamcity-mcp-server
   

   Copy

2. Pull the Docker image:

   docker pull peakflames/teamcity-remote-mcp-server
   

   Copy

3. Run the Docker container:

   docker run -d \
     --name teamcity-mcp-server \
     -p 8080:8080 \
     -e TEAM_CITY_URL="https://your-teamcity-server" \
     -e TEAM_CITY_ACCESS_TOKEN="your_access_token" \
     peakflames/teamcity-remote-mcp-server
   

   Copy

4. The server should now be running. MCP clients will connect using:

   • Streamable HTTP Transport: http://{{your-server-ip}}:8080/mcp

⁠Environment Variables

The server will fail to start if either variable is missing. Both are still required when optional authentication and per-caller RBAC (below) are enabled — the server uses its own token to query TeamCity permissions on the caller's behalf.

How to create a TeamCity access token:

1. Log in to your TeamCity server
2. Click your profile avatar (top right) > Profile
3. Go to the Access Tokens tab
4. Click Create access token
5. Give it a name and set the appropriate permissions
6. Copy the generated token (you won't be able to see it again)

⁠How It Works

1. Environment Variable Resolution: At startup, Program.cs reads TEAM_CITY_URL and TEAM_CITY_ACCESS_TOKEN from environment variables (these take precedence over appsettings.json)
2. Validation: The server throws at startup if either variable is missing or empty
3. Tool Invocation: When an MCP tool is called, the build type/configuration ID is passed as a function argument
4. Client Creation: A TeamCity HTTP client is created using Bearer token authentication with the resolved credentials

⁠Optional: Authentication and Per-Caller Access Control

TeamCityRemoteMcpServer can optionally require a bearer token from an external OAuth 2.1 authorization server, validating callers and publishing RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource/mcp. Layered on top, per-caller RBAC authorizes each tool call against the calling user's own TeamCity permissions instead of the server's shared access token. Both are off by default and behavior is unchanged unless you configure them — see docs/authentication.md⁠ and docs/rbac.md⁠.

⁠Configuring MCP Clients

⁠Claude Code (CLI)

Add the server using the streamable HTTP transport:

claude mcp add --scope user --transport http teamcity-remote http://{{your-server-ip}}:8080/mcp

If the server has authentication⁠ enabled, the client performs an OAuth flow on first connect instead of connecting immediately — that's expected, not a broken command.

⁠Cline Configuration

1. Open Cline's MCP settings UI

2. Click the "Remote Servers" tab

3. Add the following configuration:

   {
     "mcpServers": {
       "TeamCity": {
         "autoApprove": [],
         "disabled": false,
         "timeout": 60,
         "url": "http://{{your-server-ip}}:8080/mcp",
         "transportType": "streamableHttp"
       }
     }
   }
   

   Copy

⁠Troubleshooting

Server fails to start:

• Ensure both TEAM_CITY_URL and TEAM_CITY_ACCESS_TOKEN environment variables are set
• Check docker logs: docker logs teamcity-mcp-server
• Logs are also written to logs/TeamCityRemoteMcpServer_*.log inside the container

Authentication errors (401):

• Verify the access token is valid and has not expired
• Ensure the token has permission to read builds in TeamCity

401 from /mcp and the client never prompts to log in:

• Confirm the client supports RFC 9728 protected-resource discovery
• /mcp is only protected when McpAuth:Enabled=true — see docs/authentication.md⁠

Server refuses to start with an McpAuth or Rbac validation message:

• These sections are validated at startup; see the validation-error tables in docs/authentication.md⁠ and docs/rbac.md⁠

Every tool call is denied, or projects come back empty, with RBAC enabled:

• The caller's identity did not resolve, or they lack the required TeamCity permission — RBAC fails closed by design; see docs/rbac.md⁠

⁠Contributing

See CONTRIBUTING.md⁠ for development setup, build instructions, Docker publishing, and code standards.

⁠License

See LICENSE⁠ for details.