Tradesapi

contractor-license-mcp-server

实时核验美国全部 50 个州和 DC，以及 8 个主要城市的承包商执照（芝加哥、纽约市、费城、底特律、亚特兰大、达拉斯、拉斯维加斯、纳什维尔）。 这是一个 MCP 服务，可让 Claude Desktop、Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的 AI Agent，直接通过执照管理委员会门户核验承包商的执照、状态、有效期和纪律处分记录。

发送 {state, license_number, trade}，即可获取有效性、持证人姓名、到期日期、状态以及存档中的纪律处分。结果直接从州官方门户实时获取（不是过时的夜间导出数据），有效执照的结果会缓存 24 小时。

为什么选择此服务

• 覆盖美国全部 50 个州、DC 和 8 个主要城市，数据来自官方执照管理委员会门户，而非第三方数据聚合服务
• 实时查询——每次核验都会访问权威门户，因此有效期和纪律处分信息与管理委员会的数据一样新
• 批量核验——每次调用最多核验 25 个执照，并行执行
• 纪律处分记录——门户提供相关信息时会一并返回
• 由 TradesAPI 提供支持；这是一个托管式 HTTP API，也可直接调用

快速开始

托管式（推荐）

无需安装。将以下内容添加到 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"
      }
    }
  }
}

将 YOUR_API_KEY 替换为控制面板中的密钥，然后重启 Claude Desktop。

本地安装（替代方案）

如果你更倾向于通过 stdio 在本地运行 MCP 服务：

{
  "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"
      }
    }
  }
}

保存后重启 Claude Desktop。

获取 API 密钥

1. 前往 www.tradesapi.com，点击 免费注册
2. 输入电子邮件地址，你会收到一个魔法链接
3. 点击该链接进入控制面板，即可找到 API 密钥

新账户会获得 50 个免费核验额度，无需信用卡。需要更多额度时，可在控制面板购买额外额度包。

直接安装

npm install -g contractor-license-mcp-server

工具

verify_license

通过官方州（或城市）执照管理门户核验单个承包商执照。

参数	必填	描述
state	是	两字母州代码（CA、TX、FL……）
city	否	可选城市标识，用于指定市政门户：chicago、nyc、philadelphia、detroit、atlanta、dallas、lasvegas、nashville。使用小写字母，不含空格。
license_number	是	要核验的执照号码
trade	否	general、electrical、plumbing、hvac、mechanical、roofing、residential 等（默认为 general）
force_refresh	否	绕过 24 小时缓存，重新从门户获取数据
response_format	否	markdown（默认）或 json

结果示例：

## License Verification: VALID

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

batch_verify

单次调用最多核验 25 个执照。每项核验独立运行，部分失败不会影响整个批次。支持为每项指定 city。

参数	必填	描述
licenses	是	{ state, city?, license_number, trade } 对象数组（1–25 项）
response_format	否	markdown（默认）或 json

search_by_name

在单个州（或城市）的数据库中，按企业或个人姓名模糊匹配承包商。每次调用消耗 2 个额度。

参数	必填	描述
state	是	两字母州代码
city	否	市政数据库的可选城市标识
name	是	企业或个人姓名（不区分大小写，可进行部分匹配）
trade	否	工种筛选条件
limit	否	最大结果数（1–50，默认 20）
response_format	否	markdown（默认）或 json

并非所有州的门户都支持按姓名搜索——请先调用 list_supported_states，并检查每个司法辖区的 supports_name_search。

list_supported_states

列出所有受支持的辖区，包括门户 URL、当前运行状况、可用工种，以及归属各州的已注册市政爬虫。在构造其他工具调用前，可使用此工具发现哪些内容可访问。

参数	必填	描述
response_format	否	markdown（默认）或 json

覆盖范围

涵盖全部 50 个美国州和 DC（州级），以及 8 个主要城市的承包商许可门户（芝加哥、纽约市、费城、底特律、亚特兰大、达拉斯、拉斯维加斯、纳什维尔）。

通过 Agent 运行 list_supported_states，即可获取实时列表。该列表每次调用都会重新获取，包含受支持的辖区、各辖区的可用工种、当前门户运行状况，以及哪些州支持按名称搜索。MCP 软件包不再附带静态州列表——list_supported_states 返回的内容始终与生产环境同步。

你也可以在 www.tradesapi.com 查看实时州列表。

配置

变量	必填	描述
CLV_API_URL	是	API 后端 URL（使用 https://www.tradesapi.com）
CLV_API_KEY	是	你从仪表板获取的 API 密钥

额度

每次许可证验证消耗 1 个额度，无论结果是新获取的还是来自缓存。新账户可获得 50 个免费额度。你可以在仪表板上购买额外额度包：www.tradesapi.com。

开发

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

许可证

MIT