TeamCity MCP Server

Servidor MCP para JetBrains TeamCity com 87 ferramentas para builds, testes, agentes e gerenciamento de pipelines CI/CD.

GitHub
30
Experimente este MCPPatrocinado

Documentação

TeamCity MCP Server

CI CodeQL codecov License: MIT

Um servidor Model Control Protocol (MCP) que conecta assistentes de codificação com IA ao servidor CI/CD JetBrains TeamCity, expondo operações do TeamCity como ferramentas MCP.

TeamCity Server MCP server

[!NOTE] Status do projeto (junho de 2026): estável, manutenção discreta. Este projeto cumpre o que se propôs a fazer e não está mais em desenvolvimento ativo. Ele ainda funciona e permanece instalável; issues e PRs podem receber respostas lentas ou nenhuma resposta, e correções de segurança são feitas com melhor esforço.

A JetBrains agora oferece integração oficial de IA para o TeamCity — um MCP integrado e a CLI do TeamCity com uma skill de agente instalável — que é a opção padrão melhor para a maioria dos fluxos de trabalho. Veja Como isso se compara às ferramentas oficiais da JetBrains abaixo antes de adotar.

Visão Geral

O TeamCity MCP Server permite que desenvolvedores que usam assistentes de codificação com IA (Claude Code, Cursor, Windsurf) interajam com o TeamCity diretamente do seu ambiente de desenvolvimento por meio de ferramentas MCP.

Atualizando da versão 1.x? A versão 2.0.0 moveu 15 ferramentas do modo Dev para o modo Full, incluindo gerenciamento de fila, verificações de compatibilidade de agentes e monitoramento de saúde do servidor. Se você dependia dessas ferramentas no modo Dev, alterne para MCP_MODE=full ou use a alternância de modo em tempo de execução (v2.1.0+). Consulte CHANGELOG.md para detalhes.

Recursos

🚀 Dois Modos Operacionais

  • Modo Dev (padrão): Operações seguras de CI/CD (31 ferramentas, ~14 mil tokens de contexto)

    • Disparar builds e monitorar o status
    • Buscar logs de build e inspecionar falhas de teste
    • Listar projetos, configurações e fila
    • Ler parâmetros e investigar problemas

  • Modo Full: Gerenciamento completo da infraestrutura (87 ferramentas, ~26 mil tokens de contexto)

    • Todos os recursos do modo Dev, além de:
    • Criar e clonar configurações de build
    • Gerenciar etapas de build, gatilhos e dependências
    • Configurar raízes VCS e agentes
    • CRUD completo para parâmetros (config de build, projeto e parâmetros de saída)
    • Gerenciamento de fila e administração do servidor

Alternância de modo em tempo de execução (v2.1.0+): Alterne entre modos em tempo de execução usando as ferramentas get_mcp_mode e set_mcp_mode — sem necessidade de reinicialização. Clientes MCP que suportam notificações verão a lista de ferramentas ser atualizada automaticamente.

Consulte a Matriz de Modos das Ferramentas para a lista completa das 87 ferramentas e sua disponibilidade por modo.

🎯 Principais Capacidades

  • Disparar e monitorar builds, buscar logs e inspecionar falhas de teste
  • Autenticação baseada em token para o TeamCity; valores sensíveis ocultados nos logs
  • Arquitetura moderna: implementação simples e direta com um cliente singleton
  • Consciente de desempenho: inicialização rápida com sobrecarga mínima
  • Base de código limpa com limites de módulo claros

Como isso se compara às ferramentas oficiais da JetBrains

A partir de junho de 2026, a JetBrains oferece integração de IA de primeira parte para o TeamCity: um endpoint MCP integrado e a CLI do TeamCity, que inclui uma skill de agente instalável. Juntas, essas são o caminho recomendado pela JetBrains e cobrem os fluxos de trabalho comuns de IA — leitura de logs, diagnóstico de falhas e reexecução de builds — sem instalação e com suporte oficial.

O teamcity-mcp é anterior a essas ferramentas e se sobrepõe a elas. De modo geral, as ferramentas oficiais são a melhor opção padrão hoje; a vantagem restante do teamcity-mcp é um conjunto mais amplo de operações de escrita e gerenciamento expostas como um servidor MCP. Essa lacuna é real, mas está diminuindo, e as ferramentas da JetBrains evoluem rapidamente — então, em vez de fixar uma comparação recurso por recurso aqui (ela ficaria desatualizada rápido), consulte a documentação atual e escolha o que se adequa:

Se você se sente confortável com a CLI da JetBrains, talvez não precise deste projeto. Ele permanece licenciado sob MIT e instalável para o que as ferramentas integradas ainda não alcançam — faça um fork se quiser levá-lo adiante por conta própria.

Instalação

Pré-requisitos

  • Node.js >= 20.10.0 (versões LTS 20, 22, 24 testadas no CI)
  • TeamCity Server 2020.1+ com acesso à API REST
  • Token de autenticação do TeamCity

Início 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

Pacote npm

Execute o servidor MCP via npx (requer Node 20.x). Defina suas variáveis de ambiente do TeamCity inline ou por meio de um .env no diretório de trabalho.

# 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

  • Adicione o MCP (contando com .env para configuração):
    • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
  • Com variáveis de ambiente (se não estiver usando .env):
    • claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp
  • Com 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
  • Adicione -s user para instalar para o usuário em vez de apenas para o projeto (padrão)
  • Uso de contexto (Opus 4.1, estimativas):
    • Dev (padrão): ~14 mil tokens para ferramentas MCP
    • Full (MCP_MODE=full): ~26 mil tokens para ferramentas MCP

Usuários do Windows

No Windows, a configuração MCP do Claude Code pode não mesclar corretamente as variáveis de ambiente. Use argumentos de CLI como alternativa:

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

Ou use um arquivo de configuração para maior segurança (token não visível na lista de processos):

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

Configuração

O ambiente é validado centralmente com Zod. Variáveis suportadas e padrões:

# 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

Esses valores são normalizados em src/config/index.ts e consumidos por src/teamcity/config.ts por meio de getters auxiliares.

Exemplos de Uso

Depois de integrado ao seu assistente de codificação com 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"

Respostas das Ferramentas e Paginação

  • Respostas: As ferramentas agora retornam conteúdo MCP consistente. Para operações de listar/obter, o content[0].text contém uma string JSON. Formato de exemplo: { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } ou { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }.
  • Paginação: A maioria das ferramentas list_* aceita pageSize, maxPages e all:
    • pageSize controla os itens por página.
    • all: true busca várias páginas até maxPages.
    • O count legado em list_builds é mantido para compatibilidade, mas pageSize é preferido.

Validação e Erros

  • Validação de entrada: As entradas das ferramentas são validadas com esquemas Zod; entrada inválida retorna um payload de erro estruturado no conteúdo da resposta (string JSON) com success: false e error.code = VALIDATION_ERROR.
  • Formatação de erros: Os erros são formatados de forma consistente por meio de um handler global. Em produção, as mensagens podem ser sanitizadas; valores sensíveis (por exemplo, tokens) são ocultados nos logs.

Uso da 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: Os helpers legados exportados de src/teamcity/index.ts permanecem apenas para compatibilidade e incluem implementações de placeholder. Prefira as ferramentas MCP (consulte a referência vinculada acima) ou o TeamCityAPI mostrado aqui ao automatizar fluxos de trabalho.

Desenvolvimento

# 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álise de bundle no CI

O fluxo de trabalho do CI executa npm run build:bundle e envia o JSON coverage/bundles gerado usando codecov/codecov-action com o plugin javascript-bundle.

Estrutura do Projeto

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

Documentação da API

O servidor MCP expõe ferramentas para operações do TeamCity. Cada ferramenta corresponde a endpoints específicos da API REST do TeamCity:

Gerenciamento de Builds

  • TriggerBuild - Enfileirar um novo build
  • GetBuildStatus - Verificar o progresso do build
  • FetchBuildLog - Recuperar logs de build
  • ListBuilds - Pesquisar builds por critérios

Análise de Testes

  • ListTestFailures - Obter testes com falha
  • GetTestDetails - Informações detalhadas do teste
  • AnalyzeBuildProblems - Identificar motivos de falha

Configuração (Somente Modo Full)

  • create_build_config - Criar novas configurações de build do TeamCity com suporte completo para:
    • Raízes VCS (Git, SVN, Perforce) com autenticação
    • Etapas de build (script, Maven, Gradle, npm, Docker, PowerShell)
    • Gatilhos (VCS, agendamento, finish-build, maven-snapshot)
    • Parâmetros e configurações baseadas em modelos
    • Consulte a Referência de Ferramentas MCP para detalhes de argumentos e opções adicionais.
  • clone_build_config - Duplicar configurações existentes em qualquer projeto, preservando etapas, gatilhos e parâmetros.
  • update_build_config - Ajustar nomes, descrições, regras de artefatos e estado de pausa de uma configuração.
  • manage_build_steps - Adicionar, atualizar, remover ou reordenar etapas de build por meio de uma única superfície de ferramenta.
  • manage_build_triggers - Adicionar ou excluir gatilhos de build com suporte completo a propriedades.
  • create_vcs_root e add_vcs_root_to_build - Definir raízes VCS e anexá-las às configurações de build.

Veja também: docs/TEAMCITY_MCP_TOOLS_GUIDE.md para fluxos de trabalho expandidos e exemplos alinhados com a implementação MCP atual.

Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para detalhes.

Segurança

Gerenciamento de Tokens

  • Configure TEAMCITY_TOKEN por meio de variável de ambiente ou arquivo de configuração (veja .env.example); nunca faça commit de tokens reais
  • Use um token com as permissões mínimas necessárias; tokens somente leitura funcionam para a maioria das operações do modo Dev
  • Somente autenticação baseada em token; o servidor MCP não suporta usuário/senha
  • Os logs ocultam valores sensíveis, incluindo tokens

Seleção de Modo

  • Prefira o modo Dev a menos que o modo Full seja explicitamente necessário — isso limita o raio de impacto de qualquer configuração incorreta ou injeção de prompt
  • O modo Full habilita operações destrutivas (exclusão de projetos, gerenciamento de agentes) que não podem ser facilmente desfeitas

Segurança de Rede

  • Sempre use HTTPS para conexões com o TeamCity; o servidor não impõe isso, mas recomenda fortemente
  • O servidor MCP se conecta apenas à URL do TeamCity configurada; nenhuma outra chamada de rede é feita

Considerações sobre Assistentes de IA

  • Assistentes de IA podem ser manipulados por meio de injeção de prompt em logs de build, saída de testes ou outros dados do TeamCity
  • O conjunto limitado de ferramentas do modo Dev reduz o impacto desses ataques
  • Todas as ações aparecem no log de auditoria do TeamCity sob o usuário associado ao token
  • Logs de build e detalhes de falhas de teste podem conter informações sensíveis (segredos, caminhos, URLs internas) que se tornam visíveis para o assistente de IA

Segurança do Repositório

Este repositório tem a verificação de segredos do GitHub e a proteção contra push habilitadas. Consulte SECURITY.md para relatar vulnerabilidades.

Suporte

Agradecimentos

  • JetBrains TeamCity pela excelente plataforma de CI/CD
  • Anthropic pela especificação do Model Control Protocol
  • A comunidade open-source pelo suporte contínuo
  • Consulte THIRD_PARTY_NOTICES.md para licenças de terceiros

Feito com ❤️ para desenvolvedores que amam fluxos de trabalho eficientes de CI/CD