TeamCity MCP Server

Serv

GitHub
30
Prueba este MCPPatrocinado

Documentación

Servidor MCP de TeamCity

CI CodeQL codecov License: MIT

Un servidor de Protocolo de Control de Modelos (MCP) que conecta asistentes de codificación con IA al servidor CI/CD JetBrains TeamCity, exponiendo las operaciones de TeamCity como herramientas MCP.

TeamCity Server MCP server

[!NOTE] Estado del proyecto (junio de 2026): estable, mantenimiento de baja actividad. Esto cumple lo que se propuso y ya no está en desarrollo activo. Sigue funcionando y se mantiene instalable; los problemas y PRs pueden recibir respuestas lentas o nulas, y los parches de seguridad se aplican con el mejor esfuerzo.

JetBrains ahora ofrece integración oficial de IA para TeamCity — un MCP integrado y la CLI de TeamCity con una habilidad de agente instalable — que es la opción predeterminada más adecuada para la mayoría de los flujos de trabajo. Consulta Cómo se compara esto con las herramientas oficiales de JetBrains a continuación antes de adoptarlo.

Descripción general

El Servidor MCP de TeamCity permite a los desarrolladores que usan asistentes de codificación con IA (Claude Code, Cursor, Windsurf) interactuar con TeamCity directamente desde su entorno de desarrollo mediante herramientas MCP.

¿Actualizando desde 1.x? La versión 2.0.0 movió 15 herramientas del modo Dev al modo Full, incluida la gestión de colas, las comprobaciones de compatibilidad de agentes y la supervisión de la salud del servidor. Si dependías de estas herramientas en modo Dev, cambia a MCP_MODE=full o usa el cambio de modo en tiempo de ejecución (v2.1.0+). Consulta CHANGELOG.md para más detalles.

Características

🚀 Dos modos operativos

  • Modo Dev (predeterminado): Operaciones CI/CD seguras (31 herramientas, ~14k tokens de contexto)

    • Activar builds y supervisar su estado
    • Obtener registros de builds e inspeccionar fallos de pruebas
    • Listar proyectos, configuraciones y cola
    • Leer parámetros e investigar problemas

  • Modo Full: Gestión completa de la infraestructura (87 herramientas, ~26k tokens de contexto)

    • Todas las funciones del modo Dev, además de:
    • Crear y clonar configuraciones de builds
    • Gestionar pasos de build, disparadores y dependencias
    • Configurar raíces VCS y agentes
    • CRUD completo de parámetros (configuración de build, proyecto y parámetros de salida)
    • Gestión de colas y administración del servidor

Cambio de modo en tiempo de ejecución (v2.1.0+): Cambia entre modos en tiempo de ejecución usando las herramientas get_mcp_mode y set_mcp_mode — sin necesidad de reiniciar. Los clientes MCP que admiten notificaciones verán la lista de herramientas actualizarse automáticamente.

Consulta la Matriz de modos de herramientas para ver la lista completa de las 87 herramientas y su disponibilidad por modo.

🎯 Capacidades clave

  • Activar y supervisar builds, obtener registros e inspeccionar fallos de pruebas
  • Autenticación basada en tokens hacia TeamCity; los valores sensibles se redactan en los registros
  • Arquitectura moderna: implementación simple y directa con un cliente singleton
  • Consciente del rendimiento: inicio rápido con sobrecarga mínima
  • Código limpio con límites de módulos claros

Cómo se compara esto con las herramientas oficiales de JetBrains

A partir de junio de 2026, JetBrains ofrece integración de IA de primer nivel para TeamCity: un endpoint MCP integrado y la CLI de TeamCity, que incluye una habilidad de agente instalable. Juntas, estas son la vía recomendada por JetBrains y cubren los flujos de trabajo comunes de IA — leer registros, diagnosticar fallos y reejecutar builds — sin instalación y con soporte oficial.

teamcity-mcp es anterior a esas herramientas y se superpone con ellas. En general, las herramientas oficiales son la mejor opción predeterminada hoy; la ventaja restante de teamcity-mcp es un conjunto más amplio de operaciones de escritura y gestión expuestas como servidor MCP. Esa brecha es real pero se está reduciendo, y las herramientas de JetBrains evolucionan rápidamente — así que en lugar de fijar una comparación característica por característica aquí (quedaría obsoleta rápido), consulta la documentación actual y elige lo que se ajuste:

Si te sientes cómodo con la CLI de JetBrains, puede que no necesites este proyecto en absoluto. Sigue con licencia MIT e instalable para lo que las herramientas integradas aún no cubren — haz un fork si quieres llevarlo más lejos tú mismo.

Instalación

Requisitos previos

  • Node.js >= 20.10.0 (versiones LTS 20, 22, 24 probadas en CI)
  • TeamCity Server 2020.1+ con acceso a la API REST
  • Token de autenticación de TeamCity

Inicio rápido

# Clone the repository
git clone https://github.com/Daghis/teamcity-mcp.git
cd teamcity-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your TeamCity URL and token

# Run in development mode
npm run dev

Paquete npm

Ejecuta el servidor MCP mediante npx (requiere Node 20.x). Configura las variables de entorno de TeamCity en línea o mediante un .env en el directorio de trabajo.

# One-off run (inline envs)
TEAMCITY_URL="https://teamcity.example.com" \
TEAMCITY_TOKEN="<your_token>" \
MCP_MODE=dev \
npx -y @daghis/teamcity-mcp

# Or rely on .env in the current directory
npx -y @daghis/teamcity-mcp

Claude Code

  • Añade el MCP (dependiendo de .env para la configuración):
    • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
  • Con variables de entorno (si no usas .env):
    • claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp
  • Con argumentos de CLI (recomendado para Windows):
    • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev
  • Añade -s user para instalar a nivel de usuario en lugar de a nivel de proyecto (predeterminado)
  • Uso de contexto (Opus 4.1, estimaciones):
    • Dev (predeterminado): ~14k tokens para herramientas MCP
    • Full (MCP_MODE=full): ~26k tokens para herramientas MCP

Usuarios de Windows

En Windows, la configuración MCP de Claude Code puede no fusionar correctamente las variables de entorno. Usa argumentos de CLI como solución alternativa:

{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": [
        "-y",
        "@daghis/teamcity-mcp",
        "--url",
        "https://teamcity.example.com",
        "--token",
        "YOUR_TOKEN"
      ]
    }
  }
}

O usa un archivo de configuración para mayor seguridad (el token no es visible en la lista de procesos):

{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": ["-y", "@daghis/teamcity-mcp", "--config", "C:\\path\\to\\teamcity.env"]
    }
  }
}

Configuración

El entorno se valida de forma centralizada con Zod. Variables admitidas y valores predeterminados:

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# TeamCity Configuration (aliases supported)
TEAMCITY_URL=https://teamcity.example.com
TEAMCITY_TOKEN=your-auth-token
# Optional aliases:
# TEAMCITY_SERVER_URL=...
# TEAMCITY_API_TOKEN=...

# MCP Mode (dev or full)
MCP_MODE=dev

# Optional advanced TeamCity options (defaults shown)
# Connection
# TEAMCITY_TIMEOUT=30000
# TEAMCITY_MAX_CONCURRENT=10
# TEAMCITY_KEEP_ALIVE=true
# TEAMCITY_COMPRESSION=true

# Extra headers attached to every TeamCity request — useful when TeamCity
# sits behind a reverse proxy that gates access on custom headers (e.g.
# Cloudflare Zero Trust service tokens). One env var per header; the part
# after `TEAMCITY_HEADER_` is used verbatim as the HTTP header name.
# Example (note the literal hyphens — most shells need quoting):
# TEAMCITY_HEADER_CF-Access-Client-Id=<id>
# TEAMCITY_HEADER_CF-Access-Client-Secret=<secret>

# Retry
# TEAMCITY_RETRY_ENABLED=true
# TEAMCITY_MAX_RETRIES=3
# TEAMCITY_RETRY_DELAY=1000
# TEAMCITY_MAX_RETRY_DELAY=30000

# Pagination
# TEAMCITY_PAGE_SIZE=100
# TEAMCITY_MAX_PAGE_SIZE=1000
# TEAMCITY_AUTO_FETCH_ALL=false

# Circuit Breaker
# TEAMCITY_CIRCUIT_BREAKER=true
# TEAMCITY_CB_FAILURE_THRESHOLD=5
# TEAMCITY_CB_RESET_TIMEOUT=60000
# TEAMCITY_CB_SUCCESS_THRESHOLD=2

Estos valores se normalizan en src/config/index.ts y los consume src/teamcity/config.ts mediante getters auxiliares.

Ejemplos de uso

Una vez integrado con tu asistente de codificación con IA:

"Build the frontend on feature branch"
"Why did last night's tests fail?"
"Deploy staging with the latest build"
"Create a new build config for the mobile app"

Respuestas de herramientas y paginación

  • Respuestas: Las herramientas ahora devuelven contenido MCP consistente. Para operaciones de listado/obtención, el content[0].text contiene una cadena JSON. Forma de ejemplo: { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } o { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }.
  • Paginación: La mayoría de las herramientas list_* aceptan pageSize, maxPages y all:
    • pageSize controla los elementos por página.
    • all: true obtiene múltiples páginas hasta maxPages.
    • El count heredado en list_builds se mantiene por compatibilidad, pero se prefiere pageSize.

Validación y errores

  • Validación de entrada: Las entradas de las herramientas se validan con esquemas Zod; la entrada no válida devuelve una carga útil de error estructurada en el contenido de la respuesta (cadena JSON) con success: false y error.code = VALIDATION_ERROR.
  • Formato de errores: Los errores se formatean de manera consistente mediante un manejador global. En producción, los mensajes pueden sanearse; los valores sensibles (por ejemplo, tokens) se redactan en los registros.

Uso de la API

import { TeamCityAPI } from '@/api-client';

// Get the API client instance
const api = TeamCityAPI.getInstance();

// List projects
const projects = await api.listProjects();

// Get build status
const build = await api.getBuild('BuildId123');

// Trigger a new build
const newBuild = await api.triggerBuild('BuildConfigId', {
  branchName: 'main',
});

Nota: Los helpers heredados exportados desde src/teamcity/index.ts se mantienen solo por compatibilidad e incluyen implementaciones de marcador de posición. Prefiere las herramientas MCP (consulta la referencia enlazada arriba) o el TeamCityAPI mostrado aquí al automatizar flujos de trabajo.

Desarrollo

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

# Build for production
npm run build

# Analyze bundle for Codecov
npm run build:bundle

Análisis de bundle en CI

El flujo de trabajo de CI ejecuta npm run build:bundle y sube el JSON coverage/bundles generado usando codecov/codecov-action con el plugin javascript-bundle.

Estructura del proyecto

teamcity-mcp/
├── src/                    # Source code
│   ├── tools.ts           # All 87 MCP tool definitions
│   ├── server.ts          # MCP server setup
│   ├── api-client.ts      # TeamCity API singleton
│   ├── config/            # Configuration with Zod validation
│   ├── teamcity/          # Domain logic (build, agent, config managers)
│   ├── teamcity-client/   # Auto-generated OpenAPI client
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Logger, MCP helpers, pagination
├── tests/                  # Unit and integration tests
├── docs/                   # Documentation
└── scripts/                # Build and maintenance scripts

Documentación de la API

El servidor MCP expone herramientas para operaciones de TeamCity. Cada herramienta corresponde a endpoints específicos de la API REST de TeamCity:

Gestión de builds

  • TriggerBuild - Poner en cola un nuevo build
  • GetBuildStatus - Comprobar el progreso del build
  • FetchBuildLog - Recuperar registros de build
  • ListBuilds - Buscar builds por criterios

Análisis de pruebas

  • ListTestFailures - Obtener pruebas fallidas
  • GetTestDetails - Información detallada de pruebas
  • AnalyzeBuildProblems - Identificar motivos de fallo

Configuración (solo modo Full)

  • create_build_config - Crear nuevas configuraciones de build de TeamCity con soporte completo para:
    • Raíces VCS (Git, SVN, Perforce) con autenticación
    • Pasos de build (script, Maven, Gradle, npm, Docker, PowerShell)
    • Disparadores (VCS, programados, finish-build, maven-snapshot)
    • Parámetros y configuraciones basadas en plantillas
    • Consulta la Referencia de herramientas MCP para detalles de argumentos y opciones adicionales.
  • clone_build_config - Duplicar configuraciones existentes en cualquier proyecto, conservando pasos, disparadores y parámetros.
  • update_build_config - Ajustar nombres, descripciones, reglas de artefactos y estado de pausa de una configuración.
  • manage_build_steps - Añadir, actualizar, eliminar o reordenar pasos de build mediante una única superficie de herramienta.
  • manage_build_triggers - Añadir o eliminar disparadores de build con soporte completo de propiedades.
  • create_vcs_root y add_vcs_root_to_build - Definir raíces VCS y adjuntarlas a configuraciones de build.

Consulta también: docs/TEAMCITY_MCP_TOOLS_GUIDE.md para flujos de trabajo ampliados y ejemplos que se alinean con la implementación MCP actual.

Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para más detalles.

Seguridad

Gestión de tokens

  • Configura TEAMCITY_TOKEN mediante variable de entorno o archivo de configuración (consulta .env.example); nunca confirmes tokens reales
  • Usa un token con los permisos mínimos necesarios; los tokens de solo lectura funcionan para la mayoría de las operaciones del modo Dev
  • Solo autenticación basada en tokens; el servidor MCP no admite nombre de usuario/contraseña
  • Los registros redactan valores sensibles, incluidos los tokens

Selección de modo

  • Prefiere el modo Dev a menos que el modo Full sea explícitamente necesario — esto limita el radio de impacto de cualquier configuración incorrecta o inyección de prompts
  • El modo Full habilita operaciones destructivas (eliminación de proyectos, gestión de agentes) que no se pueden deshacer fácilmente

Seguridad de red

  • Usa siempre HTTPS para las conexiones a TeamCity; el servidor no lo impone, pero lo recomienda encarecidamente
  • El servidor MCP solo se conecta a la URL de TeamCity configurada; no se realizan otras llamadas de red

Consideraciones para asistentes de IA

  • Los asistentes de IA podrían ser manipulados mediante inyección de prompts en registros de build, salida de pruebas u otros datos de TeamCity
  • El conjunto limitado de herramientas del modo Dev reduce el impacto de tales ataques
  • Todas las acciones aparecen en el registro de auditoría de TeamCity bajo el usuario asociado al token
  • Los registros de build y los detalles de fallos de pruebas pueden contener información sensible (secretos, rutas, URLs internas) que se vuelven visibles para el asistente de IA

Seguridad del repositorio

Este repositorio tiene escaneo de secretos de GitHub y protección de push habilitados. Consulta SECURITY.md para informar vulnerabilidades.

Soporte

Agradecimientos

  • JetBrains TeamCity por la excelente plataforma CI/CD
  • Anthropic por la especificación del Protocolo de Control de Modelos
  • La comunidad de código abierto por el apoyo continuo
  • Consulta THIRD_PARTY_NOTICES.md para las licencias de terceros

Hecho con ❤️ para desarrolladores que aman los flujos de trabajo CI/CD eficientes