TradesAPI

contractor-license-mcp-server

Verificación de licencias de contratistas en tiempo real en los 50 estados de EE. UU. + DC, además de 8 portales de licencias de contratistas de grandes ciudades (Chicago, NYC, Filadelfia, Detroit, Atlanta, Dallas, Las Vegas, Nashville). Un servidor MCP que permite a Claude Desktop, Claude Code, Cursor, Windsurf y cualquier agente de IA compatible con MCP verificar la licencia, el estado, la fecha de vencimiento y el historial disciplinario de un contratista directamente contra los portales de las juntas de licencias.

Envía {state, license_number, trade} — recibe validez, nombre del titular de la licencia, fecha de vencimiento, estado y cualquier acción disciplinaria registrada. Los resultados se obtienen en vivo desde los portales oficiales de los estados (sin exportaciones nocturnas obsoletas) y se almacenan en caché durante 24 horas cuando está activo.

Por qué este servidor

• Los 50 estados de EE. UU. + DC + 8 grandes ciudades cubiertos a través de los portales oficiales de las juntas de licencias, no de agregadores de datos de terceros
• Consultas en vivo — cada verificación accede al portal autoritativo, por lo que los vencimientos y las acciones disciplinarias están tan actualizados como los propios datos de la junta
• Verificación por lotes — hasta 25 licencias por llamada, ejecutadas en paralelo
• Historial disciplinario — se devuelve cuando el portal lo expone
• Respaldado por TradesAPI, una API HTTP alojada a la que también puedes acceder directamente

Inicio rápido

Alojado (recomendado)

No requiere instalación. Añade esto a tu configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tradesapi": {
      "type": "streamable-http",
      "url": "https://www.tradesapi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Reemplaza YOUR_API_KEY con la clave de tu panel de control y reinicia Claude Desktop.

Instalación local (alternativa)

Si prefieres ejecutar el servidor MCP localmente mediante stdio:

{
  "mcpServers": {
    "tradesapi": {
      "command": "npx",
      "args": ["-y", "contractor-license-mcp-server"],
      "env": {
        "CLV_API_URL": "https://www.tradesapi.com",
        "CLV_API_KEY": "your-api-key-here"
      }
    }
  }
}

Reinicia Claude Desktop después de guardar.

Cómo obtener una clave API

1. Ve a www.tradesapi.com y haz clic en Regístrate gratis
2. Ingresa tu correo electrónico — recibirás un enlace mágico
3. Haz clic en el enlace y llegarás a tu panel de control, donde te espera tu clave API

Las cuentas nuevas comienzan con 50 créditos de verificación gratuitos, sin necesidad de tarjeta de crédito. Puedes comprar paquetes de créditos adicionales desde el panel de control cuando los necesites.

Instalación directa

npm install -g contractor-license-mcp-server

Herramientas

verify_license

Verifica una licencia de contratista individual contra el portal oficial de licencias del estado (o ciudad).

Parámetro	Requerido	Descripción
state	sí	Código de estado de dos letras (CA, TX, FL, ...)
city	no	Slug de ciudad opcional para apuntar a un portal municipal: chicago, nyc, philadelphia, detroit, atlanta, dallas, lasvegas, nashville. En minúsculas, sin espacios.
license_number	sí	El número de licencia a verificar
trade	no	general, electrical, plumbing, hvac, mechanical, roofing, residential, ... (por defecto general)
force_refresh	no	Omite la caché de 24 h y vuelve a obtener los datos del portal
response_format	no	markdown (por defecto) o json

Ejemplo de resultado:

## License Verification: VALID

| Field      | Value                    |
|------------|--------------------------|
| Name       | ANDERSON, ORIN RAE       |
| License #  | TACLA00000103C           |
| State      | TX                       |
| Trade      | hvac                     |
| Status     | Active                   |
| Expiration | 05/12/2026               |

batch_verify

Verifica hasta 25 licencias en una sola llamada. Cada verificación se ejecuta de forma independiente: los fallos parciales no bloquean el lote. Se admite city por elemento.

Parámetro	Requerido	Descripción
licenses	sí	Matriz de objetos { state, city?, license_number, trade } (1–25 elementos)
response_format	no	markdown (por defecto) o json

search_by_name

Coincidencia aproximada de contratistas por nombre de empresa o persona dentro de la base de datos de un solo estado (o ciudad). Cuesta 2 créditos por llamada.

Parámetro	Requerido	Descripción
state	sí	Código de estado de dos letras
city	no	Slug de ciudad opcional para bases de datos municipales
name	sí	Nombre de empresa o persona (no distingue mayúsculas, tolerante a coincidencias parciales)
trade	no	Filtro de oficio
limit	no	Máximo de resultados (1–50, por defecto 20)
response_format	no	markdown (por defecto) o json

No todos los portales estatales admiten la búsqueda por nombre: llama a list_supported_states y verifica supports_name_search por jurisdicción primero.

list_supported_states

Enumera todas las jurisdicciones admitidas con URL de portales, estado de salud actual, oficios disponibles y scrapers municipales registrados anidados bajo cada estado. Úsalo para descubrir qué es accesible antes de construir otras llamadas de herramientas.

Parámetro	Requerido	Descripción
response_format	no	markdown (por defecto) o json

Cobertura

Los 50 estados de EE. UU. + DC a nivel estatal, además de 8 portales de licencias de contratistas de grandes ciudades (Chicago, NYC, Filadelfia, Detroit, Atlanta, Dallas, Las Vegas, Nashville).

Ejecuta list_supported_states desde tu agente para obtener la lista en vivo, obtenida fresca en cada llamada, de jurisdicciones admitidas, oficios disponibles por jurisdicción, estado de salud actual de los portales y qué estados admiten búsqueda por nombre. El paquete MCP ya no incluye una tabla estática de estados: lo que devuelve list_supported_states siempre está actualizado con producción.

También puedes ver la cuadrícula de estados en vivo en www.tradesapi.com.

Configuración

Variable	Requerido	Descripción
CLV_API_URL	sí	URL del backend de la API (usa https://www.tradesapi.com)
CLV_API_KEY	sí	Tu clave API del panel de control

Créditos

Cada verificación de licencia consume 1 crédito, ya sea que el resultado sea fresco o de caché. Las cuentas nuevas reciben 50 créditos gratuitos. Se pueden comprar paquetes de créditos adicionales desde el panel de control en www.tradesapi.com.

Desarrollo

git clone https://github.com/jackunderwood/Contractor-License-Verification.git
cd Contractor-License-Verification/mcp-server
npm install
npm run build
npm test

Licencia

MIT