ParseAPI

parseapi-mcp

官方 ParseAPI MCP 服务。通过 AI Agent 查询地点、地址、公司编号、电子邮件、电话号码、天气、时区、日期等信息。

托管服务

只需一个 URL，无需安装。添加服务，然后在浏览器中登录一次即可。免费套餐可用。

{
  "mcpServers": {
    "parseAPI": { "url": "https://mcp.parseapi.com" }
  }
}

Cursor： 添加到 Cursor

仓库根目录中的 .mcp.json 故意不包含密钥。提交或刷新列表时，cursor.directory 会自动检测它。

CI 和无头环境可跳过浏览器，改用来自 parseapi.com 的密钥：

{
  "mcpServers": {
    "parseAPI": {
      "url": "https://mcp.parseapi.com",
      "headers": { "X-API-Key": "your-api-key" }
    }
  }
}

本地

{
  "mcpServers": {
    "parseAPI": {
      "command": "npx",
      "args": ["-y", "parseapi-mcp"],
      "env": { "PARSEAPI_KEY": "your-api-key" }
    }
  }
}

API 版本

从 1.0.0 版本开始，此软件包会明确选择此 MCP 软件包支持的 API 契约。每个 API 工具请求都会发送 Parse-Version: 2.0.0，与此版本的工具说明和 SDK 响应类型相匹配。本地 stdio 和托管 HTTP 均固定使用此契约，包括重试。你的密钥、OAuth 身份和团队保存的默认设置均保持不变。

对于本地 stdio，请在应用配置中固定 MCP 软件包版本，并在部署前测试新版本。未来的 MCP 主版本升级可以选择更新的 API 契约。无需为单个工具调用添加版本参数。托管服务使用其已部署的 MCP 版本所支持的 API 契约。

早于 1.0.0 的 MCP 软件包会保留现有行为，并使用团队默认设置。当旧版应用仍依赖该设置时，请保持默认设置不变。回滚到不带版本标头的软件包后，会恢复团队默认设置；因此，只有在该默认设置始终未变的情况下，回滚才能恢复旧契约。请参阅 API 版本和迁移。

工具

完整模式提供 68 个本地查询工具和 67 个托管查询工具，另外还提供用于本地元数据的 discover 和用于已认证任务估算的 preflight。ip_self 仅限本地使用。time 返回当前本地时间和 Unix 秒数。它接受时区或坐标；两者均省略时，默认为 UTC。date 解析提供的日期；若未提供，则返回 UTC 下的今天日期。现有的 timezone 调用仍受支持，且参数保持原样。每次查询都会返回 API 提供的 JSON。

工具名称遵循查询名称：country_states、city_search、postal_nearby、address、address_search、company、company_id、company_search、company_coverage、email、bank_us_ach、card、industry、industry_search、dns、asn、mac、currency_rate 等。文本搜索使用 query 参数。公司目录搜索支持选择一个名称／域名／股票代码／标识符筛选条件，或使用国家／精确 SIC 代码发现筛选条件。

现有的 naics 和 naics_search 工具仍可作为 Industry 的兼容名称使用。

Industry 付费深度记录包含分类字段 deep.exclusions，其中每项都有描述和关联代码。通用排除项可能没有关联代码。旧版响应中省略或为 null 的排除项仍表示未知。搜索结果还包含 match：匹配的 field（name、term 或 naics）和 text，以及包含拼写错误回退所用 from 和 to 词元的 corrections。精确匹配、复数匹配和前缀匹配时，corrections 为空。直接代码查询不会返回 match。旧版响应可能省略此字段。

工具参数示例：

工具	参数
stack	{"domain":"example.com"}（按类别列出网站技术和版本）
domain	{"domain":"example.com"}（注册状态）
domain	{"domain":"example.com","deep":true}（付费方案中的注册详情）
dns	{"domain":"example.com","type":"TXT"}
mx	{"domain":"example.com"}
asn	{"asn":"AS13335"}
card	{"bin":"424242"}
country_states	{"code":"US"}
address_search	{"query":"1600 Pennsylvania","country":"US","city":"Washington","state":"DC"}
company	{"number":"552100554","country":"FR"}
company_search	{"query":"Cloudflare","country":"US"}
company_id	{"id":"co_xw3f22es6cjq","deep":true}
company_coverage	{}
time	{}（当前 UTC 时间）
time	{"timezone":"America/New_York","at":"2026-09-05T09:00:00","to":"Asia/Tokyo"}
time	{"lat":40.71,"lon":-74.01}
time	{"timezone":"UTC","targets":["America/New_York","Asia/Tokyo"]}
time_zones	{"query":"New York"}
time	{"timezone":"America/New_York","at":"2026-11-01T01:30:00","to":"UTC","disambiguation":"later"}
date	{"date":"03/04/2026","format":"dmy"}
elevation	{"lat":35.2271,"lon":-80.8431}
elevation	`{"points":"35.2271,-80.8431
elevation	`{"path":"35.2271,-80.8431

只有当 at 不含偏移量且带有 to 或 targets 时，Time 才会使用 disambiguation。默认值 compatible 会选择重复时间中较早的时间，或将跳过的时间向后调整。earlier 和 later 分别选择对应的时刻。对于重复时间，reject 会返回 ambiguous_time；对于跳过的时间，则会返回 nonexistent_time。用户输入预约时间时，建议使用此参数。重试被拒绝的本地时间前，请要求用户提供明确的偏移量或选择。明确的偏移量会直接确定一个时刻。所有方案都可在同一个合并请求中使用 Time deep。

Time Deep 包含可为空的 resolution。Resolution 会报告 kind（unique、overlap 或 gap）、policy、带符号的 adjustment_seconds，以及按时间顺序排列的 alternatives，其中包含精确的本地 at、Unix 秒数和 UTC 偏移量。唯一的墙上时间没有备选项。明确指定偏移量的时间戳、当前时钟、非转换查询以及未知的源时区，其 resolution 均为 null。

Elevation 必须且只能接受以下其中一项：lat 和 lon、points，或带有 samples 的 path。点列表最多支持 512 个坐标，格式为以 | 分隔的 lat,lon 坐标对，或以 enc: 开头的 Google 编码折线，长度最多为 12000 个字符。points 响应数组会保留输入顺序和重复坐标。每个样本都包含以米和英尺为单位的高度，以及以米为单位的网格分辨率。未知样本会保持为 null。点列表使用一次合并请求；对于较长的 URL，会自动选择 JSON POST。

路径使用相同的字符串格式，包含 2–512 个顶点，并且必须提供一个介于 2 和 512 之间的整数 samples。响应中的 points 包含两个端点，并沿路径按照累积大圆距离均匀分布。每个线段都沿最短弧线延伸。由于对跖端点无法确定唯一弧线，因此包含这类端点的线段会被拒绝。路径使用一次合并请求。只有一个坐标或使用点列表时，samples 无效。

澳大利亚 postal 查询会返回核心 localities 及郊区选项（city、state、state_name）。字段值为 null 或省略表示未知；[] 表示经审核的参考资料中没有符合条件的选项。即使只有一个选项，city 也可能为 null。请询问用户选择哪个郊区，并保留手动输入选项。这些是地理位置选项，不是邮寄地址验证。AU Postal 工具结果会在 JSON 之后附带单独的来源声明。G-NAF 来源、改编内容和许可。 地址查询会返回美国和法国的标准化组成部分及注册状态。其 deep 对象目前为空。使用国家注册号查询 company 时，如果有相关信息，则会返回有效性、注册状态和业务详情。address_search 还接受 postal 和 ip，用于缩小匹配范围或调整匹配排序。法国搜索需要 country: "FR"，并且必须提供 postal 或 city。

对于公司目录，调用 company_search 时，query、domain、ticker 和 identifier 中最多只能提供一个。使用股票代码时，需同时提供 exchange；使用标识符时，需同时提供 authority。查看候选项后，将选定的 id 传给 company_id。如需获取下一页，请将返回的 next 作为 cursor，并沿用相同的选择器、筛选条件和 limit。目录深度查询会在所有套餐中通过同一个合并请求补充详情，并归属于各自的公司结果。在可用时，会返回选定的网站描述、徽标、社交账号和成立信息。会返回徽标 URL，但不会获取图片。目录工具不接受 lang。company_coverage 描述该版本收录的记录，空列表不能证明公司为私人所有。现有的 company 工具仍会解析国家注册号。

如果不使用身份选择器进行发现，请提供 country，或同时提供 industry 和 industry_type。例如：{ "country": "US", "industry": "0700", "industry_type": "sic" }。支持的命名空间为 SIC，其四位精确代码须保持为字符串。空请求、不完整的行业组合和多个选择器都会被拒绝。country 表示档案所在国家。筛选条件取交集，未知值不会匹配；返回游标时必须同时附带相同的筛选条件和 limit。仅通过筛选条件匹配的候选项会带有 match: { "field": "filters", "value": null }。

付费版 Deep 还会按发布顺序返回 taxonomies，其中包含分类代码、专科标签、主要标志，以及由数据提供方报告的许可证号码和州；此外还会返回记录日期 enumerated_at、updated_at 和 reactivated_at。报告的许可证未经核验。列表为 null 表示不可用；空列表表示该版本不含任何条目。数据提供方的记录日期描述的是其记录，而非实时核验结果。

普通查询在遇到暂时性故障后最多重试两次。如果有效的 Retry-After 指定的等待时间不超过五秒，则会遵循该时间；如果等待时间更长，则会立即返回 API 错误，不会提前重试。响应提供此标头时，错误中会包含 retry_after，其值为原始秒数或 HTTP 日期。计量查询和地址深度检查默认不重试。取消工具调用会取消待处理的 SDK 请求。

错误以带有机器可读 code 的 JSON 返回。应根据 code 分支处理，切勿根据消息文本判断。未找到时会返回 not_found。未提供密钥时会返回 invalid_api_key。

Agent 发现

在查询前，先询问 discover 某项操作可以确定哪些内容：

{ "operation": "email" }

结果包含实际输入架构，以及针对能力、时效性、不确定性、计费单位、凭证类型和重试的审核策略。JSON 文本和 MCP structuredContent 都包含相同的结果。Email、Domain、DNS、MX、Country、Time 和 timezone 发现均有经过审核的策略。其他操作会返回其输入架构，并将 policy 设为 null。字段含义因操作而异。结果未知并不意味着必须重试。

使用 { "query": "mailbox" } 查找操作。搜索默认最多返回五条摘要。detail: "full" 会包含架构和策略。使用 limit 和返回的 next_offset 翻页。元数据调用不会发出 API 请求，也不会消耗查询单位。托管 HTTP 仍需先通过现有身份验证，才能进行发现。

策略描述的是 API 合约。effective_access: "not_evaluated" 和 pricing: "not_quoted" 表示发现过程尚未检查凭证的权限、剩余额度或接受的费率。使用 preflight 获取特定账户的估算值。只读查询仍可能消耗付费单位。

在花费前，使用密钥和操作数量调用 preflight：

{
  "operations": [{ "operation": "email", "count": 100, "deep": true }],
  "budget_usd": "2.50"
}

Preflight 支持 Email、Domain、DNS、MX 和 Country，最多支持 20 行、总计 100,000 次查询。它不需要查询输入或个人数据。请同时检查 permitted、cost.status、capacity 和 budget.within_maximum。金额以十进制字符串表示。最高金额假设已用尽 Email 包含的检查次数。预计用量基于当前尚未分配的包含检查次数。未知值保持为 null。两者都使用凭证接受的费率。

估算允许每次普通查询最多尝试三次，每次 Email Deep 查询尝试一次。额外调用或重试需要重新估算。并发工作可能改变容量。Preflight 不会预留单位或金额，不会执行付费检查，也不会强制执行所提供的预算。它使用常规请求速率限制。订阅费用、税费和模型成本不包含在内。Preflight 使用 API 合约 2.0.0，以及匹配的 JavaScript SDK 1.2.0 或更高版本。

要使用精简工具目录，请在 MCP 进程中设置 PARSEAPI_MCP_MODE=compact：

PARSEAPI_MCP_MODE=compact npx -y [email protected]

在进程环境中设置 PARSEAPI_KEY，以进行查询。精简模式会公开三个工具：discover、preflight 和 lookup。发现某项操作后，传入其准确名称和参数：

{ "operation": "country", "arguments": { "code": "US" } }

lookup 使用与具名工具相同的输入验证、取消、版本固定、SDK 和计费行为。它只执行一项操作，不能运行任意代码或请求任意 URL。完整模式为默认模式，并保留现有的具名查询调用。同一进程设置也支持可自托管的 HTTP。

策略源文件是 API 的 src/route/help/agent-catalog.json。当前 API 帮助会将相同元数据公开为 agent。冻结的 API 1.0.0 帮助保持不变。在 ParseAPI 工作区中，运行 npm run catalog:sync 复制经过审核的策略变更，然后运行 npm run catalog:check。独立检出可传入 -- --source /path/to/api。软件包构建使用已检入的副本，无需 API 检出或网络请求。

批量文件

Agent 可以使用以下五种工具，以任一目录模式处理整个 CSV：

工具	操作
bulk_upload	根据文件名和精确字节数创建归账户所有的任务，并获取私有上传 URL。
bulk_preview	确认上传，分析检测到的列，选择检查项，并获取样本和报价。
bulk_start	在用户批准的 max_cost_cents 上限内，以美分为单位启动当前报价。
bulk_status	查看进度和任何所需的用户操作。
bulk_result	获取已完成文件的私有下载 URL。

Agent 需要具备文件处理能力的运行环境。使用 HTTP PUT 将 CSV 字节直接传输到 upload_url，并附带 upload_headers。先在该运行环境中将 Excel 或 Numbers 文件转换为 CSV。工具参数包含文件元数据和任务 ID，不接受文件内容、base64、源 URL 或服务器文件系统路径。

首先调用 bulk_preview，传入上传文件的 id，不传 checks，以确认上传已完成并请求分析。轮询 bulk_status，直到 job.status 为 quoted。然后调用 bulk_preview，可以选择传入 checks，例如 ["email", "phone", "ip"]，以选择检测到的列中适用的操作。更改选择会再次请求分析。重复查询状态和预览，直到响应中包含当前报价。开始前检查样本和所需设置。

bulk_start 要求传入 id、作为 quote_id 的 quote.id，以及用户批准的 max_cost_cents。传入 0 表示只允许产生零额外费用。服务器会验证报价和费用上限。付费任务在需要时会返回付款交接信息，工具不会对已保存的银行卡收费。恢复启动请求时，保持任务、报价和费用上限不变。若创建响应丢失，不得盲目再次上传。

直接获取已完成的 download_url，不要附带 API key 请求头。URL 会过期，且属于私有访问凭证。除非用户另行要求 Agent 检查文件内容，否则文件内容不会进入模型上下文。在客户的后续任务中保留原始列和未知答案。

现有 Bulk 任务 URL 仍可共享。请将任务 ID 和下载 URL 视为文件访问凭证。

现有 API key 或 OAuth 连接拥有这些任务。网站来源可通过 PARSEAPI_WEB_URL 配置，与查询 API 来源相互独立。

显示语言

此源代码候选版本为受支持的工具添加了可选的 lang。例如， country 接受 {"code":"DE","lang":"fr"}。这需要匹配的 API 本地化版本、数据和 JS SDK 软件包；安装现有已发布的 软件包并不会启用此功能。

显示名称遵循可用的源语言翻译。ID、本地名称字段、 数字和输入解析保持不变。省略语言参数时，行为保持默认设置。节假日和证明类工具没有新增 语言参数。

开发

npm install
npm run typecheck
npm test          # builds and tests with mocked fetch and in-memory MCP
npm run eval:agents # offline benchmark self-test, no model or live API calls
npm run smoke     # stdio + http, includes live API authentication checks
npm run serve     # http on :8080

离线测试会固定公共工具名称和 test/public-api.json 中的参数架构，测试每项操作和查询选项，并验证错误、重试和取消行为。请将基线变更视为公共 API 变更。发布前会先运行类型检查和离线测试。

Agent 基准测试 使用合成 API 响应，在固定任务上比较完整和精简的发现模式。其脚本化参考运行用于验证测试框架和评分，而非 Agent 的任务完成质量。在适配器提供实测用量前，模型令牌数和费用均保持为 null。夹具计费为模拟结果，始终与实时费用分开标注。

采用 MIT 许可。

可选详情

先使用默认工具调用。使用同一工具并设置 deep: true 可获取更丰富的信息。时间、日期、语言、表情符号、电话和坐标在所有套餐中均包含详情。地理档案、姓名证据和 NAICS 定义需要付费套餐。运营商和 HLR 详情仍计入同一计量核心用量，包括免费额度用量，不会额外收费，也不会触发第二道门槛。

搜索详情归属于每个返回的实体。时间转换会将目标显示详情放在 to.deep 中；只有源数据会返回 deep.next_dst。姓名核心解析无需查询词典。付费版姓名深度详情还会返回扁平字段 short、directory 和 initials。可选的 name_locale 用于选择 CLDR 格式规则，默认为 en，且不会改变解析结果和性别上下文。无法提供的格式会返回 null，较旧的响应可能不包含这些字段。国家、州和邮政税务参考信息位于付费版的 deep 数据中。

Stack API

调用 stack 工具：

{"domain":"example.com"}

传入一个不含协议、路径、端口或 IP 地址的公共主机名。Stack 会返回已检查的 URL 和 checked_at 时间，随后是 scope、pages 和 partial。scope 为 homepage 或 site；pages 统计成功检查的 HTML 页面数。仅检查首页或有界站点检查未完成时，partial 为 true。若为 false，表示已完成已知范围内的候选页面检查，并不代表访问了网站上的每个页面。首页结果的值为 scope: "homepage"、pages: 1 和 partial: true。

cms、servers、frameworks、ecommerce、analytics、chat、payments 和 hosting 均为数组，因为一个站点在每个类别中可能使用多种技术。每个条目都包含 technology、name 和可为空的 version。技术代码为开放字符串。检查成功时，没有匹配项的类别会返回空数组。如果无法检查任何 HTML 页面，checked_at 和所有类别均为 null，pages 为 0，partial 为 null。未知或冲突的版本为 null。未检测到某项技术并不能证明它不存在。

成功的检查结果最多可重复使用 24 小时。pretty 可用于格式化传输的 JSON。Stack 使用你套餐的请求额度，并由此客户端选择 API 版本 2.0.0。

首次检查时，stack 工具每次尝试最多耗时 35 秒。MCP 取消操作仍会中止请求。

time 的 targets 接受 1-10 个目的地 ID，而不是 to。单次合并请求会在同一时刻按请求顺序返回结果，并保留重复项。源坐标未知时，返回 targets: null。目的地 ID 未知时，整个请求会返回 not_found。使用 time_zones 搜索可用 ID，或省略查询以获取完整排序列表。搜索结果为空时，返回 timezones: []。

time 接受一个明确的 IP、城市、国家、IATA 机场、ICAO 机场、港口 UN/LOCODE 或地址输入。国家/州可用于缩小城市或地址范围。地址点查询目前要求提供美国国家/地区上下文。港口参考数据仅涵盖经过审核的 UN/LOCODE 子集。托管调用绝不会根据服务器推断用户的 IP。输入有歧义或缺失时，时钟字段和 location 候选项会返回 null。请询问缺失的上下文，或让用户自行选择，不要静默选定某个候选项。

time_zones 可按国家、IANA 区域、精确偏移量、缩写、某一时刻是否实行夏令时，或 UTC 日历年内是否出现夏令时来筛选。它会保留明确设为 false 的筛选条件。details 会添加详细条目和通用评估时刻，默认标识符列表则保持精简。缩写会返回候选时区。Source deep 会公开标准偏移量和带符号的季节性偏移量，以及实际夏令时季节的转换边界。负数季节性调整和 null 边界均保留其原有含义。

银行工具会在 POST JSON 请求体中发送原始 IBAN、路由号码和账户字符串，避免账户输入出现在 URL 中。bank 保留可选的国家和 deep 控制项。若执行了目录查询，deep 目录证据会指出不可变的源版本和实际匹配粒度；但这并不能证明国家范围完整或网络可达。bank_us_ach 接受路由号码和账户字符串，并检查 ABA 路由校验和以及账户字段语法。它没有 deep 选项，无法验证账户校验和、账户是否存在、账户所有权或 ACH 资格。请保留所有账户字符和前导零。bank_requirements 接受国家以及可选的格式（默认为 iban，也可以是 us_ach），并返回接受的字段、检查范围和限制。要求属于元数据，不代表银行覆盖情况。请避免记录包含银行输入的工具参数或请求体。

当 US ACH 返回银行名称时，MCP 会在未经更改的 JSON 结果旁附带单独的路由号码参考归属声明。

Emoji 目录新增功能

解析 Unicode 表情符号或命名短码，搜索或浏览有界目录， 解析文本中的表情符号位置，并在 Unicode 与所选短码来源之间进行转换。 普通查询仍返回四个字段：

GET /emoji/rocket

{"emoji":"🚀","name":"Rocket","shortcodes":[":rocket:","rocket"],"category":"Travel & Places"}

使用 deep=true 获取 Unicode 属性、关键词、肤色系列和可用作品。 核心值保持不变。文本解析会返回包含 UTF-16 positions 的 emojis； 转换会返回 text，以及包含位置和原因的未解析词元。

精简版 JSON 目录包含离线身份、资格形式和短码索引。 需要作品时，请请求 profile=full；需要本地化名称和关键词时，请请求 lang。 /emoji/metadata 一次性提供数据集覆盖范围和共享来源声明。 作品支持 Google Noto、Twemoji 和 OpenMoji，并提供实际可用的 SVG/PNG 和不可变的一方 URL。 设备的表情符号字体仍用于常规显示。

这些新增功能在匹配的 SDK 和后端发布之前，仍属于本地候选版本。现有查询和搜索约定保持不变。

标准 City 操作

经典查询、搜索、最近项和按名称查询附近地点的方法保留其默认封装和必填字段模型。浏览和按坐标查询附近地点使用标准列表：object、data 和可空的 next_cursor（在 Swift/Kotlin 中为 camelCase 属性）。继续翻页时，请保持所有查询选项不变；客户端不会自动获取后续页面。

{"operation":"city_search","arguments":{"query":"Viena","format":"list","match":"fuzzy","max_distance":1}}

选择 format=resource 获取单个 City，或选择 format=list 获取集合。集合支持国家包含/排除集合、时区集合、包含端点的人口和海拔（米）范围、存储中心点的 bbox，以及带符号的多键排序。未知的数值属性不符合范围筛选条件。

搜索默认使用前缀匹配。精确匹配和模糊匹配需显式指定；模糊匹配接受最大编辑距离 1 或 2，并返回 match 证据（type、source、value、language、edit_distance）。存储其 ID 前，请先核实模糊匹配结果。

经过审核的子级、祖先和同级项使用标准列表，但关系覆盖范围可能不完整。数据为空并不能证明不存在地理关系。子级/同级项支持分页控制；祖先项不支持。距离会报告存储中心点之间的大圆距离（公里和英里）：零表示已知距离为零，null 表示未知，且不代表行程时间或包含关系。

严格模式 ambiguity=error 可返回 HTTP 409 ambiguous_city，并附带最多两个安全候选身份。现有错误构造函数和无关错误元数据保持不变；候选项仅在该状态码/错误码下保留，且绝不包含 Deep。GeoJSON 可通过 HTTP 获取；这些带类型的 City 列表方法不会返回 GeoJSON。

各国家/地区的覆盖范围和可用字段见 https://parseapi.com/city#coverage。

romanized=true 会请求经过审核的官方名称形式，作为 name_romanized 和 romanization_language 返回（在 Swift/Kotlin 中为 camelCase）。目前经过审核的形式涵盖 20 个日文整座城市别名，语言标签为 ja-Latn。缺失或冲突的形式保持为 null；不会以 ASCII 折叠替代官方形式。

条件请求 If-None-Match 和 GeoJSON 目前需直接使用 HTTP。匹配的 City ETag 会返回不带正文的 304；常规计费和速率限制仍适用。这些 JSON 客户端方法不提供条件缓存处理。