Verika - Verifica P.IVA, Codice Fiscale e IBAN

Verika · partita-iva-mcp

用于验证意大利标识符的 MCP 服务——增值税号、税号、IBAN——并通过免费的官方数据源（VIES、IPA、GLEIF、ISTAT、欧盟制裁名单）丰富相关信息。

专为使用或构建 AI Agent 的用户打造，帮助他们检查意大利公司和机构（入驻、轻量级 KYC、向公共管理部门开具发票、清理登记信息），无需集成四个不同的 API。

立即使用

服务已上线，免费且无需密钥：无需安装或注册。

• 端点：https://partita-iva-mcp.pons-labs.workers.dev/mcp
• 传输方式：Streamable HTTP（远程 MCP）
• 身份验证：无

Claude（桌面端、网页端、移动端）——设置 → 连接器 → 添加自定义连接器 → 粘贴端点 → 添加。在新聊天中，通过 + → 连接器 启用。需要支持自定义连接器的套餐。

Claude Code

claude mcp add --transport http partita-iva --scope user https://partita-iva-mcp.pons-labs.workers.dev/mcp

Cursor、VS Code 和其他客户端，使用 JSON 配置：

{
  "mcpServers": {
    "partita-iva": { "url": "https://partita-iva-mcp.pons-labs.workers.dev/mcp" }
  }
}

该服务也已发布到 MCP 官方注册表，名称为 io.github.JackPons/partita-iva-mcp。

示例

启用连接器后，可以向助手提出以下问题：

• “帮我整理这家公司的增值税号信息［一个真实的增值税号，例如从发票上获取］：是否有效？注册地在哪里？” → scheda_soggetto 返回 VIES 状态、名称、通过 ISTAT 标准化的地址（市镇、省、地区）、制裁筛查结果、LEI 及法律形式和企业集团信息（如果企业有所属集团）；如果是公共管理部门，还会返回 IPA 代码和 PEC。
• “这个税号有效吗？RSSMRA85T10A562S。此人出生在哪里？” → valida_codice_fiscale 验证校验字符，并推导性别、出生日期和出生地（此处为 San Giuliano Terme，PI）。
• “检查 IBAN：DE89 3704 0044 0532 0130 00” → valida_iban 验证校验位；对于意大利 IBAN，还会拆分 ABI、CAB 和账号，并在已知的情况下指出银行。
• “Bank Rossiya 在欧盟制裁名单上吗？” → controlla_sanzioni 返回可能的匹配项及相似度评分（结果为 da_verificare）。
• “我有 10 家供应商的增值税号清单：告诉我哪些似乎未处于有效状态” → 助手会为每家供应商调用 verifica_partita_iva 并汇总结果。

valida_iban 的响应示例（节选）：

{
  "normalizzato": "DE89370400440532013000",
  "valido": true,
  "paese": "DE",
  "formattato": "DE89 3704 0044 0532 0130 00"
}

工具

工具	功能	外部调用
valida_partita_iva	格式检查（11 位数字、校验位、办事处代码）	否
verifica_partita_iva	VIES 状态：有效／无效、名称、地址	VIES
valida_codice_fiscale	校验字符、同形异码、性别、出生日期和出生地（ISTAT 市镇或外国）；11 位数字 → 法人	否
valida_iban	验证所有国家的 Mod 97；对于意大利 IBAN，还会检查 CIN、ABI → 银行、CAB、账号	否
cerca_comune	按名称或地籍代码查询市镇：省、地区、ISTAT 代码	否
controlla_sanzioni	对照欧盟综合名单进行提示性名称筛查，采用容错匹配并提供评分	否
scheda_soggetto	根据增值税号提供完整信息：格式检查 + VIES，并通过 ISTAT 标准化地址 + 制裁筛查 + 若为公共管理部门则提供 IPA 数据 + LEI、法律形式、母公司及子公司数量（GLEIF）	VIES、IPA、GLEIF

每条响应都会标明来源以及服务是否可访问，避免 Agent 将“无效”与“无法验证”混为一谈。

本地开发

用于修改服务或运行自己的副本。要求：Node.js 22+、npm；部署需要 Cloudflare 账户（免费套餐即可）。

npm install
npm run dati        # scarica le tabelle ISTAT e la lista sanzioni UE in src/data/ (una volta, poi ogni tanto)
npm test            # test unitari, nessuna rete necessaria
npm run inspect     # apre MCP Inspector sul server stdio
npm run dev         # server HTTP locale su http://localhost:8787/mcp

在 VS Code 中，.vscode/mcp.json 文件已配置好 stdio 服务：打开命令面板 → MCP: List Servers → partita-iva-locale。

在 Claude Code 中，启动本地 HTTP 服务后：

claude mcp add partita-iva -t http http://localhost:8787/mcp

部署到 Cloudflare Workers

npx wrangler login
npm run deploy

端点为 https://partita-iva-mcp.<tuo-subdominio>.workers.dev/mcp。主页（/）显示连接说明，/health 返回 {ok:true}。

使用统计与隐私

Worker 会在 Cloudflare D1 中统计调用次数，并为每位用户应用每分钟 60 次请求的速率限制。两者都是可选的：即使不进行配置，服务也能正常运行。

每次调用会保存的内容：日期和时间、MCP 方法、工具名称、客户端（例如 claude-ai）、国家/地区、结果、耗时，以及一个由 IP + 日期 + 秘密盐值生成的用户标识哈希。

不会保存的内容：工具参数（增值税号、税号、IBAN、姓名）和 IP 地址。哈希每天都会变化，因此可以统计一天内的不同用户数量，但无法长期追踪用户。超过 90 天的记录会在每晚删除。

配置（仅需一次）

npx wrangler d1 create partita-iva-mcp-stats     # copia il database_id in wrangler.jsonc
npm run db:migra                                 # crea la tabella sul D1 remoto
npx wrangler secret put STATS_TOKEN              # una stringa lunga a caso: protegge /stats
npx wrangler secret put HASH_SALT                # un'altra stringa a caso: sale per l'hash degli IP
npm run deploy

本地开发时：运行 npm run db:migra-locale，并创建文件 .dev.vars（已从 git 中排除），其中包含 STATS_TOKEN=... 和 HASH_SALT=...。

查看统计数据

curl -H "Authorization: Bearer $STATS_TOKEN" https://<tuo-worker>/stats?giorni=30

也可以在浏览器中访问 https://<tuo-worker>/stats?token=...。该页面会返回总数、每天的调用次数和用户数、各工具的调用次数和错误数、客户端及国家/地区。

发布到注册表

1. 更新 server.json（名称为 io.github.<utente>/<server>，包含版本号，以及末尾带有 /mcp 的 URL）。每次发布都必须使用新版本。
2. 官方注册表：安装 mcp-publisher，然后运行 mcp-publisher validate、mcp-publisher login github、mcp-publisher publish。PulseMCP 和 Glama 会从那里收录。
3. Smithery：在 smithery.ai/new 提交端点 URL；每次部署后，前往 Releases → Publish，启动新一轮扫描。
4. 意大利目录：按照其 CONTRIBUTING 说明，向 bsab/italia-mcp-servers 提交 PR。

本地表格（src/data/）

JSON 文件最初是 seed（仅含少量条目，供测试使用）。运行 npm run dati 会将其替换为：

• comuni.json — 包含所有 ISTAT 市镇及其地籍代码、省份、大区和 ISTAT 代码
• sanzioni.json — 欧盟金融制裁汇总清单（id、类型、名称/别名、计划）

stati-esteri.json（Z 代码）和 abi.json（银行）是手动编制的、不完整的表格：需要核实并扩充。ABI 的权威来源是 Banca d'Italia 的中介机构名单；如果找到官方 CSV，请为脚本添加一个处理分支。

每个使用表格的工具都会在输出中声明表格是 seed 还是已更新（infoTabelle）；在运行 npm run dati 之前，controlla_sanzioni 会返回 lista_non_caricata：明确表示“不知道”总比错误地声称“没有匹配项”好。

结构

src/
  lib/            algoritmi puri e client delle fonti (testabili senza MCP)
    partita-iva.ts
    codice-fiscale.ts
    iban.ts
    vies.ts
    ipa.ts
    gleif.ts      LEI, forma giuridica e gruppo
    tabelle.ts    accesso alle tabelle locali
    sanzioni.ts   matching contro la lista UE
  data/           tabelle JSON (seed → aggiornate da npm run dati)
  server.ts       definizione degli strumenti MCP (condivisa)
  telemetria.ts   conteggio chiamate (D1), rate limit, statistiche
  stdio.ts        entrypoint locale
  worker.ts       entrypoint Cloudflare Workers (Streamable HTTP, stateless)
migrations/       schema SQL del database D1
scripts/
  aggiorna-dati.ts  scarica e converte le tabelle ufficiali
test/             node:test, con fetch finto per VIES, IPA e GLEIF

来源与限制

所有工具均为只读：不会修改数据，也不会向第三方发送任何内容，但向 VIES、IPA 和 GLEIF 发起查询除外。速率限制：每位用户每分钟 60 次请求。

• VIES（欧盟委员会）：查询增值税用途的欧盟内部 VAT 号状态。对于意大利，通常会返回名称和地址；有时会暂时无法使用，服务器会对此进行提示。
• IPA（indicepa.gov.it，CKAN 开放数据）：用于识别公共行政机构并获取 IPA 代码、PEC 和网站。
• GLEIF（api.gleif.org，CC0 许可证）：全球 LEI 注册库。按税号搜索已在企业注册处登记的公司；返回法律形式、LEI 状态、直接母公司、最终母公司和子公司数量。LEI 主要由中大型企业以及在金融市场运营的企业持有：对于小型企业，trovato: false 属于正常情况。
• ISTAT（市镇列表）：标准化市镇名称和地籍代码。
• 欧盟综合制裁清单：按名称进行筛查，仅供参考。不能替代 AML 服务提供商或操作人员的判断；转写为其他文字的名称（阿拉伯文、西里尔文）可能无法通过词元匹配识别。
• 服务器不会访问企业注册处：股东、职位、财务报表和抗议信息均为付费数据，因此不包含在此版本中。
• 从税号中提取的出生日期，其世纪为推断所得（anno_ambiguo: true）。

返回的数据受原始数据源许可证约束。

路线图

• 根据地籍代码获取市镇，根据 Z 代码获取外国国家
• 根据 ABI 获取银行（部分表格）
• 欧盟制裁筛查
• 按工具统计调用次数（D1），不含个人数据
• 基本速率限制
• 所有工具的输出架构和只读注释
• 可选 API key，提供更高限额
• CAP → 市镇（ISTAT/Poste）
• 在主体信息卡中加入 ANAC（已授予的采购合同）和 RNA（国家援助）
• ATECO 代码说明

许可证

MIT。