uChecker

Validación de correos electrónicos para agentes de IA: verifica direcciones mediante SMTP/MX, detecta correos desechables, catch-all y de rol, rastrea tareas y exporta listas limpias.

GitHubPrueba este MCPPatrocinado

Servidor MCP alojado

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

Se instala en Claude Code, Codex, Cursor y más

Documentación

Servidor MCP de UChecker

Un servidor MCP para la API de validación de correos electrónicos UChecker. Permite que un asistente de IA valide direcciones de correo, realice seguimiento de tareas de validación, lea resultados por dirección y analíticas de cuenta, y exporte listas limpiadas, sin que tengas que escribir ningún código de integración.

Diez herramientas, tres recursos y dos indicaciones guiadas, tanto sobre stdio (local) como HTTP Streamable (remoto).

Inicio rápido

Local (stdio)

Necesitas una clave de API de UChecker desde 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_..." }
    }
  }
}

La clave también se puede pasar como --api-key=uk_.... Compila primero con npm ci && npm run build.

Remoto (HTTP Streamable)

Una instancia alojada se ejecuta en https://api.uchecker.net/mcp. Es sin estado: la clave de API viaja en cada solicitud y no se mantiene ninguna sesión entre llamadas.

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_... también funciona. Verificación de estado: GET /mcp/health. Para ejecutar tu propia instancia, consulta docs/DEPLOYMENT.md.

El endpoint remoto se autentica con una cabecera de clave de API, no con OAuth, por lo que los clientes que solo pueden usar OAuth o no pueden establecer cabeceras personalizadas necesitan la versión stdio.

Configuración

Variable	Modo	Predeterminado	Propósito
`UCHECKER_API_KEY`	stdio	—	Obligatoria. También se puede establecer mediante `--api-key=`.
`UCHECKER_API_URL`	ambos	`https://api.uchecker.net`	API ascendente. También `--api-url=` en stdio.
`UCHECKER_PUBLIC_API_URL`	http	`https://api.uchecker.net`	URL mostrada a los usuarios en las sugerencias de descarga, cuando el servidor accede a la API a través de una red interna.
`MCP_PORT`	http	`3009`	Puerto de escucha.

En modo HTTP, la clave nunca se configura en el servidor: proviene de la cabecera x-api-key o Authorization: Bearer de cada solicitud, por lo que una instancia atiende a muchas cuentas.

Herramientas

Herramienta	Qué hace	Consume créditos
`validate_email`	Pone en cola una dirección para validación	1
`validate_emails`	Pone en cola un lote (máx. 10 000 por llamada)	1 por dirección
`get_task_status`	Estado y progreso de una tarea	—
`wait_for_task`	Sondea hasta que se complete/falla, con notificaciones de progreso	—
`get_task_results`	Resultados por dirección, paginados y filtrables	—
`get_task_analytics`	Conteos, % de entregabilidad, motivos de rechazo	—
`export_results`	Guarda la lista completa de resultados en un archivo (stdio) o devuelve un comando curl (http)	—
`list_tasks`	Historial de tareas paginado	—
`get_account_balance`	Créditos restantes	—
`get_account_stats`	Totales y promedios de toda la cuenta	—

Referencia completa de parámetros y salidas: docs/TOOLS.md.

Recursos

uchecker://account/balance — créditos restantes
uchecker://tasks — las 20 tareas más recientes
uchecker://tasks/{taskId}/analytics — analíticas de una tarea

Indicaciones

clean_email_list(source?) — flujo de trabajo integral: consultar saldo, validar en lotes, esperar, exportar listas limpias de buenos/malos, informar entregabilidad
deliverability_report() — tendencia de entregabilidad entre tareas recientes

Cómo funciona la validación

Las direcciones se ponen en cola, no se verifican de forma síncrona. validate_email y validate_emails devuelven un task_id inmediatamente; la tarea avanza por pending → processing → completed. Una lista de cinco direcciones normalmente se completa en menos de un minuto, pero las listas más grandes tardan proporcionalmente más, por lo que:

prefiere wait_for_task sobre un bucle manual de get_task_status — emite notificaciones de progreso de MCP mientras espera y devuelve timed_out: true en lugar de quedarse colgado para siempre;
para listas largas, pasa webhook_url y deja que la API te llame de vuelta;
usa get_task_analytics cuando solo necesites agregados — es mucho más económico que extraer cada fila.

Cada dirección termina como good, bad o unknown. unknown significa que la verificación no pudo llegar a un veredicto (MX inalcanzable, greylisting, ambigüedad de catch-all) — no es sinónimo de inválido.

Desarrollo

El servidor se ejecuta en Node 20+; el conjunto de herramientas de prueba necesita Node 22.12+.

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

Una prueba de humo en vivo ejecuta el servidor stdio compilado contra una API real:

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

Gasta un crédito en una llamada real a validate_email, así que apúntalo a staging a menos que estés verificando deliberadamente producción.

Arquitectura: src/core/ contiene el servidor independiente del transporte (cliente de API, herramientas, recursos, indicaciones); src/stdio.ts y src/http.ts son los dos puntos de entrada. Añadir una herramienta significa tocar solo src/core/tools.ts.

Lectura adicional:

docs/TOOLS.md — referencia de herramientas
docs/DEPLOYMENT.md — autoalojamiento con Docker detrás de un proxy inverso
docs/API-NOTES.md — peculiaridades de la API ascendente que este servidor absorbe
CHANGELOG.md

Licencia

MIT