orizn-visa-mcp

Orizn Visa API MCP 服务

Orizn Visa API MCP 服务是一个模型上下文协议（MCP）服务，可为 AI 助手提供任意护照与目的地组合对应的签证和入境要求，并支持 15 种语言。

覆盖范围持续扩大：我们不在此处列出可能过时的数字，而是通过 get_coverage_stats 工具从 API 实时读取覆盖数据（也可通过 https://visa.orizn.app/api/v1/visa/stats 公开查看）。

它可以回答诸如“从法国去日本需要签证吗”“美国公民去中国需要哪些文件”“持印度护照在伊斯坦布尔转机时可以离开机场吗”等问题——提供的是数据，而非猜测。

兼容性

此服务通过 stdio 使用 MCP 通信，并可在 Node.js 18 或更高版本上运行。它适用于任何能够启动 stdio 服务的 MCP 客户端，包括 Claude Desktop、Claude Code 和 Cursor。以下配置代码块适用于它们所有客户端。

安装

npx orizn-visa-mcp

无需构建，也无需克隆。将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "orizn-visa": {
      "command": "npx",
      "args": ["-y", "orizn-visa-mcp"]
    }
  }
}

重启客户端，然后提问：“从法国去日本需要签证吗？”——无需 API 密钥即可使用，每天可查询 10 次。

其他所有功能（文件、费用、办理时间、过境规则和 15 种语言）都需要添加一个免费密钥：

{
  "mcpServers": {
    "orizn-visa": {
      "command": "npx",
      "args": ["-y", "orizn-visa-mcp"],
      "env": {
        "ORIZN_API_KEY": "orizn_visa_..."
      }
    }
  }
}

也可以将密钥作为参数传入，此时参数优先于环境变量：

npx orizn-visa-mcp --api-key orizn_visa_...

示例问题

• “从法国去泰国旅游需要签证吗？”
• “作为美国公民去中国，需要哪些文件？”
• “巴西护照持有者去泰国、越南和印度尼西亚，哪个更合适？”
• “持中国护照在伊斯坦布尔转机 12 小时期间可以离开机场吗？”
• “菲律宾护照持有者办理申根签证需要多少钱？”
• “持法国护照入境巴西需要接种哪些疫苗？”
• “泰国签证逾期 3 天会被罚款多少？”
• “葡萄牙有数字游民签证吗？费用是多少？”
• “请用法语回答：持摩洛哥护照去日本需要签证吗？”

工具

工具	参数	返回内容	套餐
check_visa_requirement	passport、destination、lang	一种护照前往一个目的地的完整入境要求：要求类型、允许停留天数、所需文件、申请步骤、费用、办理时间、护照有效期、照片规格、疫苗接种、保险、安全提示、逾期停留处罚、航空／陆路／海路入境、远程工作签证、延期及未成年人规定、大使馆。	任意密钥
quick_visa_check	passport、destination	一行信息：要求代码、免签天数，以及最后核实这组信息的日期。不含文件、费用或翻译。	无 — 无密钥时每天 10 次，使用任意密钥可无限次调用
compare_destinations	passport、destinations（1–25）、lang	并列比较一种护照前往最多 25 个目的地的情况：要求、免签天数、说明、护照有效期、费用、安全、健康、疫苗接种、保险、按入境方式划分的要求、远程工作签证。每个返回的目的地计为一次请求。	Starter 或更高套餐
check_transit_visa	passport、transit_country、lang	仅限中转停留规定：旅客转机时能否留在机场隔离区内或离开机场，以及主要枢纽提供多少小时的免签中转停留时间。	Starter 或更高套餐
get_coverage_stats	无	数据库规模：国家／地区组合、护照、目的地、翻译、语言，以及各类入境要求的分布。不涉及任何特定组合。	无
get_recent_changes	passport、destination、since、limit（均可选）	近期发生变化的签证规定，以及报告该变化的来源和日期。该动态目前已关闭 — 见下文。	无

国家／地区代码采用 ISO 3166-1 alpha-3（FRA、JPN、USA），而非 alpha-2。

requirement 的取值包括 visa_free、visa_required、e_visa、visa_on_arrival、eta、no_admission，以及较少见的 partial_restrictions、admission_refused、not_applicable 和 special。

资源

visa://supported-languages — lang 接受的 15 种语言代码，所有套餐（包括免费套餐）均可使用：en fr es pt de ja ko zh ru it ar hi th vi tl。

get_recent_changes 有意返回空结果

Orizn 的政策变更动态已关闭。该动态曾将两个 Orizn 内部表格之间检测到的不一致当作官方政策变更提供，因此现在会返回 HTTP 503，且此工具会降级为：

{ "status": "unavailable", "changes": [], "do_not_conclude": "This is NOT evidence that no visa rules changed..." }

该工具有意以此状态发布：明确标注的空结果才是诚实的做法；等到该动态开始使用经过核实的官方来源运行时，工具便会开始返回真实条目——届时，没有注明来源名称和日期的条目将被扣留，而不会显示。

身份验证和免费套餐

quick_visa_check、get_coverage_stats 和 get_recent_changes 完全不需要 API 密钥。无密钥的 quick_visa_check 每天最多可检查 10 次，与 visa.orizn.app 为匿名访客提供的额度相同。超过限额后，该工具会明确提示并指向免费密钥，而不会静默失败。限额按运行中的服务进程计算，并于 00:00 UTC 重置。

另外三个工具需要 API 密钥，并通过 x-api-key 标头发送到 https://visa.orizn.app/api/v1/visa。

前往 visa.orizn.app/visa-api 免费获取，无需信用卡。免费套餐每月提供 100 次请求（确认电子邮件地址前为 5 次），并包含核心字段和全部 15 种语言。免费套餐不提供更深入的字段——费用、处理天数、照片规格、疫苗接种、保险、过境签证、按入境方式查询、逾期停留处罚、远程工作签证、大使馆——这些字段会返回 {"upgrade": "..."} 占位内容，且 compare_destinations 和 check_transit_visa 受限。

Starter 套餐每月 49 美元，可请求 30,000 次，并解锁所有功能，同时提供商业许可：升级。更多高用量套餐请见定价页面。

将密钥传入 MCP 配置的 env 块中——MCP 客户端不会继承你的 Shell 环境，因此仅在终端中导出 ORIZN_API_KEY 并不足够。

无需任何 MCP 客户端即可检查密钥：

curl -H "x-api-key: $ORIZN_API_KEY" \
  "https://visa.orizn.app/api/v1/visa/check?passport=FRA&destination=JPN"

{ "passport": "FRA", "destination": "JPN", "requirement": "visa_free", "visa_free_days": 90 }

故障排除

症状	解决方法
“No Orizn API key”	对仅限密钥的工具来说，这是预期行为。quick_visa_check 仍会返回结果。若要解除限制，请将密钥放入配置文件的 env 块中，而不是 Shell 环境中，然后重启客户端
“Keyless daily limit reached”	今天的 10 次免费检查额度已用完。免费密钥可解除此限制
HTTP 403，“check ORIZN_API_KEY for typos”	密钥有误、已撤销或包含空格
HTTP 403，“requires Starter plan or above”	密钥正确，但套餐不符——此工具需要付费
HTTP 429	月度额度已用完
查询真实国家时出现 HTTP 404	请使用 alpha-3 代码（FRA、JPN），而非 alpha-2（FR、JP）
完全无法使用	调用 get_coverage_stats——它不需要密钥。如果它也失败了，问题出在网络
get_recent_changes 返回空列表	这是预期行为——动态信息源正在重建。这不代表规则没有变化

链接

• 网站 — visa.orizn.app
• API 文档 — visa.orizn.app/visa-api/dashboard/docs
• 获取免费密钥 — visa.orizn.app/visa-api
• GitHub — github.com/MattJeff/orizn-mcp-server
• 支持 — [email protected]

许可证

MIT