mcp-doctor

mcp-doctor

Diagnostique, proteja e avalie o desempenho dos seus servidores MCP.

CLI de configuração zero que descobre automaticamente as configurações de servidores MCP em Claude Code, Cursor, VS Code, Windsurf e Claude Desktop — depois testa conexões, sinaliza problemas de segurança e avalia a latência em segundos.

Por quê?

Servidores MCP estão se tornando a espinha dorsal do desenvolvimento assistido por IA. Mas, à medida que você adiciona mais servidores em mais ferramentas, as coisas quebram silenciosamente:

• Servidores caem e você só percebe quando uma chamada de ferramenta falha no meio da conversa
• Segredos vazam — chaves de API codificadas em arquivos de configuração, tokens visíveis nos argumentos de processos
• Servidores lentos arrastam todo o seu fluxo de trabalho de IA sem que você perceba
• Configurações divergem entre ferramentas — o que funciona no Cursor pode estar quebrado no Claude Desktop

O mcp-doctor oferece um único comando para verificar tudo, em todas as ferramentas, em segundos.

Início Rápido

npx @wigu/mcp-doctor doctor

É isso. Sem configuração necessária — ele encontra seus servidores automaticamente.

Comandos

Comando	Descrição
doctor	Executa todas as verificações de uma vez (scan + segurança + benchmark)
scan	Testa todas as conexões dos servidores MCP
security	Audita configurações em busca de problemas de segurança
bench	Avalia os tempos de resposta dos servidores
serve	Executa como um servidor MCP (transporte stdio)

Todos os comandos suportam --json para saída legível por máquina.

doctor — Verificação completa (recomendado)

Executa scan, segurança e benchmark de uma só vez e imprime um resumo.

mcp-doctor doctor

# JSON output for CI/scripts
mcp-doctor doctor --json

scan — Testa todas as conexões dos servidores MCP

Descobre configurações e verifica se cada servidor responde a um handshake JSON-RPC.

$ mcp-doctor scan

  ┌─────────────────────────────────────────┐
  │           mcp-doctor v0.3.0             │
  │   Diagnose · Secure · Benchmark         │
  └─────────────────────────────────────────┘

  ✔ Found 3 server(s)

  ┌──────────────┬────────────┬─────────┐
  │ Server       │ Source     │ Status  │
  ├──────────────┼────────────┼─────────┤
  │ filesystem   │ Claude     │ ✔ OK    │
  │ postgres     │ Cursor     │ ✔ OK    │
  │ slack        │ VS Code    │ ✘ FAIL  │
  └──────────────┴────────────┴─────────┘

security — Audita configurações em busca de problemas de segurança

Verifica segredos vazados, permissões excessivamente amplas e padrões de comando arriscados.

$ mcp-doctor security

  ⚠  2 issues found

  ┌──────────┬──────────┬───────────────────────────────┐
  │ Severity │ Server   │ Issue                         │
  ├──────────┼──────────┼───────────────────────────────┤
  │ HIGH     │ postgres │ Plaintext password in config  │
  │ MEDIUM   │ slack    │ Token visible in args         │
  └──────────┴──────────┴───────────────────────────────┘

bench — Avalia os tempos de resposta dos servidores

Mede a latência de ida e volta JSON-RPC para cada servidor configurado.

$ mcp-doctor bench

  ┌──────────────┬──────────┬────────┐
  │ Server       │ Latency  │ Rating │
  ├──────────────┼──────────┼────────┤
  │ filesystem   │ 12ms     │ fast   │
  │ postgres     │ 87ms     │ ok     │
  │ slack        │ timeout  │ —      │
  └──────────────┴──────────┴────────┘

Modo Servidor MCP

O mcp-doctor também pode ser executado como um servidor MCP, expondo scan, security, bench e doctor como ferramentas que seu assistente de IA pode chamar diretamente.

{
  "mcpServers": {
    "mcp-doctor": {
      "command": "npx",
      "args": ["@wigu/mcp-doctor"]
    }
  }
}

Quando invocado sem argumentos e com stdin canalizado, ele inicia automaticamente no modo servidor usando transporte stdio. Você também pode executar explicitamente:

mcp-doctor serve

Isso significa que seu assistente de IA pode diagnosticar sua própria infraestrutura MCP sob demanda.

GitHub Action

Use o mcp-doctor na CI para detectar servidores quebrados e segredos vazados automaticamente:

- name: Check MCP servers
  uses: realwigu/mcp-doctor@main
  with:
    command: doctor
    fail-on-error: "true"

A action gera JSON via ${{ steps.mcp-doctor.outputs.result }} para processamento downstream.

Saída JSON

Todos os comandos suportam --json para saída estruturada — útil para pipelines de CI, dashboards ou scripts:

mcp-doctor doctor --json | jq '.summary'

{
  "servers": 3,
  "healthy": 2,
  "securityIssues": 1,
  "avgLatencyMs": 45
}

Ferramentas Suportadas

Ferramenta	Config Auto-Detectada
Claude Code	✅
Claude Desktop	✅
Cursor	✅
VS Code	✅
Windsurf	✅

O mcp-doctor lê o arquivo de configuração de cada ferramenta em seu local padrão e mescla todos os servidores descobertos em uma única visão.

O Que Ele Verifica

• Saúde da conexão — handshake JSON-RPC initialize contra cada servidor
• Problemas de segurança — segredos em texto puro, tokens em argumentos, comandos shell perigosos
• Benchmarks de latência — tempo de ida e volta com classificações rápido / ok / lento

Instalação

# Run directly (no install needed)
npx @wigu/mcp-doctor scan

# Or install globally
npm install -g @wigu/mcp-doctor
mcp-doctor scan

Requer Node.js 18+.

Contribuindo

Contribuições são bem-vindas! Abra uma issue ou envie um pull request.

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b my-feature)
3. Faça commit das suas alterações
4. Abra um PR

Licença

MIT