TradesAPI

contractor-license-mcp-server

Verificação de licença de contratante em tempo real em todos os 50 estados dos EUA + DC, além de 8 portais de licenciamento de contratantes de grandes cidades (Chicago, NYC, Filadélfia, Detroit, Atlanta, Dallas, Las Vegas, Nashville). Um servidor MCP que permite ao Claude Desktop, Claude Code, Cursor, Windsurf e qualquer agente de IA compatível com MCP verificar a licença, o status, a expiração e o histórico disciplinar de um contratante diretamente nos portais das juntas de licenciamento.

Envie {state, license_number, trade} — receba de volta validade, nome do licenciado, data de expiração, status e quaisquer ações disciplinares registradas. Os resultados são obtidos ao vivo dos portais oficiais dos estados (sem exportações noturnas desatualizadas) e armazenados em cache por 24 horas quando ativo.

Por que este servidor

• Todos os 50 estados dos EUA + DC + 8 grandes cidades cobertos via portais oficiais das juntas de licenciamento, não agregadores de dados de terceiros
• Consultas ao vivo — cada verificação acessa o portal autoritativo, então expirações e ações disciplinares estão tão atualizadas quanto os próprios dados da junta
• Verificação em lote — até 25 licenças por chamada, executadas em paralelo
• Histórico disciplinar — retornado quando o portal o expõe
• Com suporte do TradesAPI, uma API HTTP hospedada que você também pode acessar diretamente

Início rápido

Hospedado (recomendado)

Nenhuma instalação necessária. Adicione isto à sua configuração do 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"
      }
    }
  }
}

Substitua YOUR_API_KEY pela chave do seu painel e reinicie o Claude Desktop.

Instalação local (alternativa)

Se preferir executar o servidor MCP localmente via 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"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar.

Obtendo uma chave de API

1. Acesse www.tradesapi.com e clique em Cadastre-se grátis
2. Digite seu e-mail — você receberá um link mágico
3. Clique no link e acesse seu painel, onde sua chave de API está aguardando

Novas contas começam com 50 créditos gratuitos de verificação, sem necessidade de cartão de crédito. Você pode comprar pacotes adicionais de créditos pelo painel quando precisar de mais.

Instalação direta

npm install -g contractor-license-mcp-server

Ferramentas

verify_license

Verifique uma única licença de contratante no portal oficial de licenciamento do estado (ou cidade).

Parâmetro	Obrigatório	Descrição
state	sim	Código de estado com duas letras (CA, TX, FL, ...)
city	não	Slug opcional da cidade para direcionar um portal municipal: chicago, nyc, philadelphia, detroit, atlanta, dallas, lasvegas, nashville. Minúsculas, sem espaços.
license_number	sim	O número da licença a ser verificado
trade	não	general, electrical, plumbing, hvac, mechanical, roofing, residential, ... (padrão: general)
force_refresh	não	Ignorar o cache de 24h e buscar novamente no portal
response_format	não	markdown (padrão) ou json

Exemplo 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

Verifique até 25 licenças em uma única chamada. Cada verificação é executada de forma independente — falhas parciais não bloqueiam o lote. O city por item é suportado.

Parâmetro	Obrigatório	Descrição
licenses	sim	Matriz de objetos { state, city?, license_number, trade } (1–25 itens)
response_format	não	markdown (padrão) ou json

search_by_name

Correspondência aproximada de contratantes por nome comercial ou individual dentro do banco de dados de um único estado (ou cidade). Custa 2 créditos por chamada.

Parâmetro	Obrigatório	Descrição
state	sim	Código de estado com duas letras
city	não	Slug opcional da cidade para bancos de dados municipais
name	sim	Nome comercial ou individual (insensível a maiúsculas/minúsculas, tolerante a correspondência parcial)
trade	não	Filtro de ofício
limit	não	Máximo de resultados (1–50, padrão 20)
response_format	não	markdown (padrão) ou json

Nem todo portal estadual suporta busca por nome — chame list_supported_states e verifique supports_name_search por jurisdição primeiro.

list_supported_states

Liste todas as jurisdições suportadas com URLs dos portais, saúde atual, ofícios disponíveis e scrapers municipais registrados aninhados sob cada estado. Use isto para descobrir o que está acessível antes de construir outras chamadas de ferramentas.

Parâmetro	Obrigatório	Descrição
response_format	não	markdown (padrão) ou json

Cobertura

Todos os 50 estados dos EUA + DC no nível estadual, além de 8 portais de licenciamento de contratantes de grandes cidades (Chicago, NYC, Filadélfia, Detroit, Atlanta, Dallas, Las Vegas, Nashville).

Execute list_supported_states a partir do seu agente para obter a lista ao vivo, buscada fresca a cada chamada, de jurisdições suportadas, ofícios disponíveis por jurisdição, saúde atual do portal e quais estados suportam busca por nome. O pacote MCP não inclui mais uma tabela estática de estados — o que retorna de list_supported_states está sempre atualizado com a produção.

Você também pode ver a grade de estados ao vivo em www.tradesapi.com.

Configuração

Variável	Obrigatório	Descrição
CLV_API_URL	sim	URL do backend da API (use https://www.tradesapi.com)
CLV_API_KEY	sim	Sua chave de API do painel

Créditos

Cada verificação de licença consome 1 crédito, seja o resultado novo ou em cache. Novas contas recebem 50 créditos gratuitos. Pacotes adicionais de créditos podem ser comprados no painel em www.tradesapi.com.

Desenvolvimento

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

Licença

MIT