uChecker

npx add-mcp 'https://api.uchecker.net/mcp'

Servidor MCP UChecker

Um servidor MCP para a API de validação de e-mail UChecker. Ele permite que um assistente de IA valide endereços de e-mail, acompanhe tarefas de validação, leia resultados por endereço e análises da conta, e exporte listas limpas — sem que você precise escrever qualquer código de integração.

Dez ferramentas, três recursos e dois prompts guiados, via stdio (local) ou HTTP Streamable (remoto).

Início rápido

Local (stdio)

Você precisa de uma chave de API UChecker de app.uchecker.net.

// Claude Desktop: claude_desktop_config.json
// Claude Code:    .mcp.json
{
  "mcpServers": {
    "uchecker": {
      "command": "node",
      "args": ["/path/to/mcp/build/stdio.js"],
      "env": { "UCHECKER_API_KEY": "uk_..." }
    }
  }
}

A chave também pode ser passada como --api-key=uk_.... Compile primeiro com npm ci && npm run build.

Remoto (HTTP Streamable)

Uma instância hospedada roda em https://api.uchecker.net/mcp. Ela é stateless: a chave de API viaja em cada requisição, e nenhuma sessão é mantida entre chamadas.

curl -X POST https://api.uchecker.net/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-api-key: uk_...' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_account_balance","arguments":{}}}'

Authorization: Bearer uk_... também funciona. Verificação de saúde: GET /mcp/health. Para executar sua própria instância, veja docs/DEPLOYMENT.md.

O endpoint remoto autentica com um cabeçalho de chave de API, não OAuth, então clientes que só conseguem fazer OAuth ou não podem definir cabeçalhos personalizados precisam da versão stdio.

Configuração

Variável	Modo	Padrão	Finalidade
UCHECKER_API_KEY	stdio	—	Obrigatório. Também configurável via --api-key=.
UCHECKER_API_URL	ambos	https://api.uchecker.net	API upstream. Também --api-url= em stdio.
UCHECKER_PUBLIC_API_URL	http	https://api.uchecker.net	URL mostrada aos usuários nas dicas de download, quando o servidor acessa a API por uma rede interna.
MCP_PORT	http	3009	Porta de escuta.

No modo HTTP, a chave nunca é configurada no lado do servidor — ela vem do cabeçalho x-api-key ou Authorization: Bearer de cada requisição, então uma única instância atende muitas contas.

Ferramentas

Ferramenta	O que faz	Custa créditos
validate_email	Enfileira um endereço para validação	1
validate_emails	Enfileira um lote (máx. 10 000 por chamada)	1 por endereço
get_task_status	Status e progresso de uma tarefa	—
wait_for_task	Consulta até concluir/falhar, com notificações de progresso	—
get_task_results	Resultados por endereço, paginados e filtráveis	—
get_task_analytics	Contagens, % de entregabilidade, motivos de rejeição	—
export_results	Salva a lista completa de resultados em um arquivo (stdio) ou retorna um comando curl (http)	—
list_tasks	Histórico de tarefas paginado	—
get_account_balance	Créditos restantes	—
get_account_stats	Totais e médias da conta	—

Referência completa de parâmetros e saídas: docs/TOOLS.md.

Recursos

• uchecker://account/balance — créditos restantes
• uchecker://tasks — 20 tarefas mais recentes
• uchecker://tasks/{taskId}/analytics — análises de uma tarefa

Prompts

• clean_email_list(source?) — fluxo de trabalho ponta a ponta: verificar saldo, validar em lotes, aguardar, exportar listas limpas de bons/ruins, relatar entregabilidade
• deliverability_report() — tendência de entregabilidade nas tarefas recentes

Como a validação funciona

Endereços são enfileirados, não verificados de forma síncrona. validate_email e validate_emails retornam um task_id imediatamente; a tarefa passa por pending → processing → completed. Uma lista de cinco endereços normalmente termina em menos de um minuto, mas listas maiores levam proporcionalmente mais tempo, então:

• prefira wait_for_task em vez de um loop manual com get_task_status — ele emite notificações de progresso MCP enquanto aguarda e retorna timed_out: true em vez de travar para sempre;
• para listas longas, passe webhook_url e deixe a API chamar você de volta;
• use get_task_analytics quando você só precisar de agregados — é muito mais barato do que puxar cada linha.

Cada endereço termina como good, bad ou unknown. unknown significa que a verificação não conseguiu chegar a um veredito (MX inacessível, greylisting, ambiguidade de catch-all) — não é sinônimo de inválido.

Desenvolvimento

O servidor roda em Node 20+; o conjunto de ferramentas de teste precisa de Node 22.12+.

npm ci
npm run build        # tsc -> build/
npm test             # vitest, no network

Um teste de fumaça ao vivo executa o servidor stdio compilado contra uma API real:

UCHECKER_API_KEY=uk_... UCHECKER_API_URL=https://api.staging.uchecker.net \
  node tests/live-staging.mjs [completedTaskId]

Ele gasta um crédito em uma chamada real de validate_email, então aponte para o ambiente de staging, a menos que você esteja deliberadamente verificando a produção.

Arquitetura: src/core/ contém o servidor independente de transporte (cliente de API, ferramentas, recursos, prompts); src/stdio.ts e src/http.ts são os dois pontos de entrada. Adicionar uma ferramenta significa mexer apenas em src/core/tools.ts.

Leitura adicional:

• docs/TOOLS.md — referência de ferramentas
• docs/DEPLOYMENT.md — auto-hospedagem com Docker atrás de um proxy reverso
• docs/API-NOTES.md — peculiaridades da API upstream que este servidor absorve
• CHANGELOG.md

Licença

MIT