flipzi-mcp

Flipzi MCP 服务

向 Claude、Cursor 或任何 MCP 客户端询问集换式卡牌价格：搜索卡牌、获取当前价格、已售商品对比数据、价格历史、市场涨跌榜、游戏和系列。这是对 Flipzi Data API 的轻量本地封装。你需要自备 Flipzi API 密钥；免费计划无需绑定银行卡。

通过 stdio（npx）在你的计算机上运行。没有任何托管服务，唯一的网络流量是你向 data.flipzi.io 发出的请求。

源码：https://github.com/flipzitcg/flipzi-mcp。这是公开镜像；如有问题，请通过 GitHub Issues 报告，而非提交拉取请求。

1. 获取密钥（免费）

1. 创建账户：https://flipzi.io/account/register?product=data&utm_source=npm&utm_medium=directory&utm_campaign=202610_mcp
2. 验证电子邮件。系统会为你创建免费密钥额度（每月 500 个单位，每分钟 5 次请求）。
3. 在 https://flipzi.io/account/keys 创建密钥（密钥以 fz_live_ 开头，且只会显示一次）。

2. 将密钥添加到你的 AI 工具

需要 Node.js 18+。将 fz_live_... 替换为你的密钥。

Claude Code

claude mcp add --env FLIPZI_API_KEY=fz_live_... --transport stdio flipzi -- npx -y @flipzitcg/mcp

使用 claude mcp list 或 /mcp 检查。添加 --scope user 可在每个项目中使用。

Claude Desktop（一键安装） — 发布后，从 GitHub releases 下载 flipzi-mcp.mcpb 并打开；Claude Desktop 会在遮蔽字段中要求你输入密钥。

Claude Desktop（配置文件） — 进入 Settings → Developer → Edit Config（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json），然后完全退出并重新打开应用：

{
  "mcpServers": {
    "flipzi": {
      "command": "npx",
      "args": ["-y", "@flipzitcg/mcp"],
      "env": { "FLIPZI_API_KEY": "fz_live_..." }
    }
  }
}

Cursor — 将相同的代码块添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。不要提交包含密钥的文件。

然后询问：“Umbreon VMAX 现在值多少钱？”，或调用 flipzi_account 查看你的计划。

工具

工具	需要	单位	功能
flipzi_account	任意密钥	0	查看你的计划、已用额度，以及计划解锁的工具
flipzi_list_games	Free	1	支持的游戏
flipzi_list_sets	Free	1	某个游戏的系列
flipzi_list_set_cards	Free	1	某个系列中的卡牌（获取卡牌 ID）
flipzi_search_cards	Free	1	按名称搜索
flipzi_get_card	Free	1	卡牌详情
flipzi_get_price	Free	1	当前价格、市场价格和置信度（评级卡牌需要 Pro）
flipzi_get_history	Basic	1	每日历史记录（Basic 提供 30 天，Pro+ 提供更长时间）
flipzi_get_sold_comps	Pro	1	买家在 eBay 上的实际成交价
flipzi_get_movers	Ultra	5	某个游戏中涨幅最大或跌幅最大的卡牌
flipzi_get_box_value	Pro	1	密封补充包盒的价格与盒内卡牌的估算价值（通过校验的英文版 Pokémon 卡盒；仅提供范围，不作保证）
flipzi_get_cardmarket_conditions	Ultra	1	按语言、工艺和 Cardmarket 等级（Mint 至 Poor）列出 Cardmarket 要价：最低价和中位数，并注明读取日期

所需计划依据 API 自身的契约（openapi.yaml，版本见 src/plans.generated.ts）读取，而非猜测。计划和价格：https://flipzi.io/api/pricing/?utm_source=npm&utm_medium=directory&utm_campaign=202610_mcp。**始终会列出所有工具。**如果你的计划不包含某项工具，该工具会说明这一点、指出支持该工具的计划、提供升级链接，并且拒绝调用不扣除任何单位。

用量与限制

• 每次调用消耗 1 个单位（movers 消耗 5 个）。API 按 UTC 月份统计每个账户的用量；flipzi_account 会显示剩余用量。
• 免费计划每分钟允许 5 次请求。短暂等待（≤10 s）会自动重试一次；更长的等待会报告出来。
• **会话预算：**此服务每次运行消耗达到 FLIPZI_MCP_MAX_UNITS 个单位后会自行停止（默认为 150），以免 Agent 循环耗尽你当月的用量。设置为 0 表示不限制。重启服务即可重置。
• 每次调用的输出上限约为 20 KB；搜索默认返回 10 张卡片。

设置（环境变量）

变量	默认值
FLIPZI_API_KEY	必填	你的密钥。绝不会打印或记录。
FLIPZI_MCP_MAX_UNITS	150	每次运行的单位预算，0 = 不限
FLIPZI_MCP_NO_CLIENT_TAG	未设置	设为 1 可停止发送下方的客户端标头
FLIPZI_API_BASE	https://data.flipzi.io	仅用于测试

发送的内容，以及 Flipzi 能了解到的信息（无隐藏遥测）

• 你的请求会像任何 API 客户端一样，携带密钥发送到 data.flipzi.io。不会进行其他网络调用，也没有分析服务、更新检查或远程控制。
• 每个请求都会携带 User-Agent: flipzi-mcp/<version> 和 X-Flipzi-Client: mcp/<version>。Flipzi 只会记录调用来自 MCP 服务（值为 mcp），以便统计 MCP 用量，并了解用户尝试使用哪些受计划限制的工具。将 FLIPZI_MCP_NO_CLIENT_TAG=1 设为退出统计；其他功能不受影响。
• 此服务输出的链接（注册、密钥、升级）包含 utm_source=mcp，因此 Flipzi 可以知道账户是从此处开始的。这些只是普通查询参数，可以删除。
• 提示词、对话和卡片查询不会发送到其他地方；它们只会作为你所请求调用的 API 参数发送。

故障排除

• “FLIPZI_API_KEY is not set” — 客户端配置的 env 中缺少密钥；编辑后请重启客户端。
• 工具未显示在 Claude Desktop 中 — 完全退出并重新打开；检查 ~/Library/Logs/Claude/mcp-server-flipzi.log（macOS）或 %APPDATA%\Claude\logs（Windows）。在 Windows 上，如果 npx 失败，请全局安装 npm（npm install -g npm）。
• “Not on your plan” — 这是预期情况；请参阅表格。运行 flipzi_account。
• 联系支持时，请提供错误中的 request_id。请参阅 SUPPORT.md。

免费计划不授予商业用途许可。数据仅供参考；请参阅 API 条款。采用 MIT 许可。