TestRail MCP Server

Interaja com o TestRail para gerenciar casos de teste, projetos, suítes e exec

Documentação

TestRail MCP Server

Este servidor Model Context Protocol (MCP) fornece ferramentas para interagir com o TestRail diretamente do Claude AI e de outros clientes compatíveis com MCP, como o Cursor. Ele permite gerenciar casos de teste, projetos, suítes, execuções e muito mais sem sair da sua conversa com a IA.

Ferramentas Disponíveis

O servidor MCP do TestRail fornece as seguintes ferramentas:

Categoria	Ferramentas
Projetos	`getProjects`, `getProject`
Suítes	`getSuites`, `getSuite`, `addSuite`, `updateSuite`
Casos	`getCase`, `getCases`, `addCase`, `updateCase`, `deleteCase`, `getCaseTypes`, `getCaseFields`, `copyToSection`, `moveToSection`, `getCaseHistory`, `updateCases`, `addBdd`, `getBdd`
Seções	`getSection`, `getSections`, `addSection`, `moveSection`, `updateSection`, `deleteSection`
Execuções	`getRuns`, `getRun`, `addRun`, `updateRun`
Testes	`getTests`, `getTest`
Resultados	`getResults`, `getResultsForCase`, `getResultsForRun`, `addResultForCase`, `addResultsForCases`
Planos	`getPlans`
Marcos	`getMilestones`
Passos Compartilhados	`getSharedSteps`

Uso

Você pode conectar este servidor MCP configurando como abaixo. Este método usa npx para baixar e executar automaticamente a versão mais recente do pacote, eliminando a necessidade de instalação local.

// Example configuration using npx
{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["@bun913/mcp-testrail@latest"],
      "env": {
        "TESTRAIL_URL": "https://your-instance.testrail.io", // Replace with your TestRail URL
        "TESTRAIL_USERNAME": "your-email@example.com", // Replace with your TestRail username
        "TESTRAIL_API_KEY": "YOUR_API_KEY" // Replace with your TestRail API key
      }
    }
  }
}

Solução de Problemas

spawn npx ENOENT / spawn node ENOENT (comum no macOS): seu host MCP (Cursor, Claude Code, Claude Desktop, …) não consegue encontrar npx ou node no momento da criação do processo. A interface de chat geralmente exibe isso como um erro genérico "o servidor MCP não funciona" sem detalhes úteis; o log por servidor é a fonte de verdade para diagnóstico.

Por que isso acontece no macOS: aplicativos GUI iniciados pelo Dock, Spotlight ou Finder herdam o PATH mínimo do launchd (/usr/bin:/bin:/usr/sbin:/sbin). Se você instalou o Node por meio de um gerenciador de versões (nvm, asdf, mise, fnm, Volta) ou Homebrew para Apple Silicon (/opt/homebrew/bin/), o npx fica fora desse PATH — apenas o arquivo de inicialização do seu shell (~/.zshrc / ~/.bashrc) o adiciona. Seu terminal funciona porque o shell executou o arquivo de inicialização; o processo do aplicativo GUI nunca o executou.

Diagnostique verificando o log por servidor em busca de spawn npx ENOENT:
- Cursor: ~/Library/Application Support/Cursor/logs/<session>/window<N>/exthost/anysphere.cursor-mcp/MCP <server>.log
- Claude Code / Claude Desktop: ~/Library/Logs/Claude/
Correção: substitua "npx" na sua configuração MCP pelo caminho absoluto. Execute which npx no seu terminal normal:
```
/Users/you/.nvm/versions/node/v24.15.0/bin/npx   # nvm
/opt/homebrew/bin/npx                            # Apple Silicon Homebrew
/usr/local/bin/npx                               # Intel Homebrew / system Node
```
Em seguida, atualize sua configuração MCP:
```
{
  "mcpServers": {
    "testrail": {
      "command": "/Users/you/.nvm/versions/node/v24.15.0/bin/npx",
      "args": ["@bun913/mcp-testrail@latest"],
      "env": {
        "TESTRAIL_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your-email@example.com",
        "TESTRAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```
Reinicie seu cliente MCP após a alteração. A mesma correção se aplica a todos os servidores MCP iniciados por npx — se mcp-testrail estiver falhando por esse motivo, seus outros servidores iniciados por npx provavelmente também estão falhando.
Problemas de autenticação: verifique suas credenciais da API do TestRail.
Sua conversa está muito longa: use os parâmetros limit e offset para casos de teste e seções a fim de paginar os resultados.
Erros HTTP 400 ao criar/atualizar casos de teste: os projetos do TestRail possuem diferentes modelos, campos personalizados e campos obrigatórios. Este servidor MCP envia seus parâmetros diretamente para a API do TestRail — ele não os valida nem os transforma. Se você encontrar erros 400, defina as regras do seu projeto em CLAUDE.md ou AGENTS.md para que o LLM envie os parâmetros corretos. Por exemplo:
```
# TestRail Rules for This Project
- Project ID: 1
- Always use template 2 (Separated Steps) when creating test cases
  - Use `customStepsSeparated` (array of step objects)
  - Do NOT send `customSteps` or `customExpected` with template 2
- Required custom fields: custom_automation_type (default: 0)
- Call `getCaseFields` at the start of a session to check available fields
```

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

TestRail MCP Server

Documentação