fonzip

这是一个独立的开源项目，由 Fonzip Yazılım A.Ş. 之外的团队开发，不受其支持或认可。

让 Claude Code、Claude Desktop、Cursor、VS Code、Codex 和其他支持 MCP 的客户端直接访问您的 Fonzip 数据。

Sen:    Bu ay kaç düzenli bağışçı kaydolmuş, toplam ne kadar?
Ajan:   [fonzip_donations / list çağrılır]
        Ağustos'ta 34 yeni düzenli bağışçı, aylık toplam 41.250 TL.

• 13 个工具，涵盖 Fonzip API v2 的 113 项操作
• 工具定义由 OpenAPI spec 自动生成 — 无需手动保持同步
• OAuth2 client_credentials，包括跨进程保存 token
• 土耳其语错误消息；调用出错时会将预期的架构返回给模型

安装

需要 Node.js 20 或更高版本。首先在 Fonzip 中打开 设置 > 高级 > Fonzip API，然后创建 API 密钥；您将获得一个 client_id 和一个 client_secret。

重要

Fonzip 密钥以 $2b$12$... 开头。在 shell 中请使用单引号 — 如果使用双引号或不加引号，shell 会将 $2b 和 $12 部分视为变量并删除，导致收到 HTTP 403。JSON 文件不受此问题影响。

claude mcp add fonzip \
  -e FONZIP_CLIENT_ID='...' \
  -e FONZIP_CLIENT_SECRET='...' \
  -- npx -y @ubaranzorlu/fonzip-mcp

{
  "mcpServers": {
    "fonzip": {
      "command": "npx",
      "args": ["-y", "@ubaranzorlu/fonzip-mcp"],
      "env": {
        "FONZIP_CLIENT_ID": "...",
        "FONZIP_CLIENT_SECRET": "..."
      }
    }
  }
}

{
  "mcpServers": {
    "fonzip": {
      "command": "npx",
      "args": ["-y", "@ubaranzorlu/fonzip-mcp"],
      "env": {
        "FONZIP_CLIENT_ID": "...",
        "FONZIP_CLIENT_SECRET": "..."
      }
    }
  }
}

code --add-mcp '{"name":"fonzip","command":"npx","args":["-y","@ubaranzorlu/fonzip-mcp"],"env":{"FONZIP_CLIENT_ID":"...","FONZIP_CLIENT_SECRET":"..."}}'

{
  "inputs": [
    { "type": "promptString", "id": "fonzip-id", "description": "Fonzip client id", "password": true },
    { "type": "promptString", "id": "fonzip-secret", "description": "Fonzip client secret", "password": true }
  ],
  "servers": {
    "fonzip": {
      "command": "npx",
      "args": ["-y", "@ubaranzorlu/fonzip-mcp"],
      "env": {
        "FONZIP_CLIENT_ID": "${input:fonzip-id}",
        "FONZIP_CLIENT_SECRET": "${input:fonzip-secret}"
      }
    }
  }
}

[mcp_servers.fonzip]
command = "npx"
args = ["-y", "@ubaranzorlu/fonzip-mcp"]
env = { FONZIP_CLIENT_ID = "...", FONZIP_CLIENT_SECRET = "..." }

komut:    npx
argüman:  -y @ubaranzorlu/fonzip-mcp
ortam:    FONZIP_CLIENT_ID, FONZIP_CLIENT_SECRET

验证

向客户端提问：“显示我的 Fonzip 账户信息” — 服务应通过调用 fonzip_system / me 返回您的机构名称。

环境变量

¹ 未提供 FONZIP_ACCESS_TOKEN 时为必需。

工具

Fonzip API v2 有 115 个操作。如果每个操作都是一个独立工具，客户端的工具列表就会变得臃肿；因此，我们按主题将操作分组到 13 个工具中。每个工具都需要一个 action 参数。

/token 和 /authorize 端点不会作为工具提供；身份验证由服务器自行处理。

调用示例：

{
  "name": "fonzip_donations",
  "arguments": {
    "action": "list",
    "status": "paid",
    "start_date": "2026-01-01T00:00:00+03:00",
    "end_date": "2026-01-31T23:59:59+03:00"
  }
}

架构模式

在 full（默认）模式下，每个工具的所有参数都会以 JSON Schema 的形式发送给客户端。13 个工具的架构总计约 70 KB（约 1.9 万个 token）；模型可以在单轮中构造正确的调用。

如果上下文预算有限，请使用 FONZIP_SCHEMA_MODE=compact：架构会精简为 action 和一个自由格式的 params 对象，字段名称则在工具说明中概述。总计约 22 KB（约 6 千个 token），即 full 模式的三分之一。如果发送了缺失字段，错误消息会返回该 action 的完整架构，以便模型自行修正。

两种模式都接受普通格式（{"action": "get", "user_id": 1}）和包装格式（{"action": "get", "params": {"user_id": 1}}）。

须知事项

Fonzip 同一时间只发放一个 token。 有效 token 存在时，调用 /token 会返回 HTTP 409 "Token already created"。由于 MCP 服务经常重启，token 默认会保存到 ~/.cache/fonzip-mcp/tokens.json 文件中（权限为 0600，且不写入 client id），并在重启时重复使用。如果关闭此缓存，服务器重启后可能长达一小时都无法获取 token。

必须提供 User-Agent。 Fonzip 前面的 Cloudflare 会以 HTTP 403 (error code 1010) 拒绝没有 User-Agent 请求头的请求。请勿将 FONZIP_USER_AGENT 留空。

速率限制为每分钟 240 个请求。 收到 HTTP 429 时，会遵循 Retry-After 请求头进行重试。

交易列表需要日期范围。 以下 action 必须提供 start_date 和 end_date；如果缺少，请求会在发送到 Fonzip 之前被拒绝：

fonzip_donations → list、list_micro、report · fonzip_membership_dues → list · fonzip_events → list_ticket_sales · fonzip_forms → list_answers · fonzip_ecards → list_transactions

如果未提供分页参数（start_page，默认值为 1）和页面大小（how_many，默认值为 10，最大值为 100），系统会自动添加默认值。同样，fonzip_donations / list 的 status 默认值为 paid。

写入操作已启用。 服务器提供所有 CRUD 操作；删除操作无法撤销。包含删除操作的工具会标记 MCP destructiveHint，客户端可能会要求确认。如果您只需要读取权限，请在 Fonzip 中创建具有只读权限的 API 密钥。

个人数据会发送给模型。 Fonzip 响应可能包含姓名、电子邮件、电话号码、土耳其身份证号码和 IBAN；这些数据会传输到您的 MCP 客户端和所使用的模型。请根据您的 KVKK 义务进行评估。详情请参阅 SECURITY.md。

较大的响应会被截断。 超过 100,000 个字符的响应会被截断，建议使用分页。

开发

git clone https://github.com/ubaranzorlu/fonzip-mcp.git
cd fonzip-mcp
npm install
npm test        # 97 test
npm run build

仓库中包含 .mcp.json；运行 npm run build 后，Claude Code 会通过本项目本地的 dist/ 运行服务。您必须在 shell 中设置 FONZIP_CLIENT_ID 和 FONZIP_CLIENT_SECRET。

工具定义不会手动编写——scripts/generate.ts 会根据 openapi/fonzip-v2.yaml 生成 src/generated/operations.ts。详情和版本发布步骤请参阅 CONTRIBUTING.md。

贡献

欢迎贡献。开始之前，请阅读 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。如需报告安全漏洞，请参阅 SECURITY.md。

许可证

本仓库中的代码采用 MIT 许可证 © Umut Baran Zorlu。

openapi/fonzip-v2.yaml 是 Fonzip Yazılım A.Ş. 自有的 API 文档，不受 MIT 许可证约束；它仅作为生成工具定义的参考资料存放在仓库中。同样的例外也适用于从该规范派生的 src/generated/operations.ts 和已发布的 dist/ 内容。“Fonzip”名称仅用于说明该服务连接到哪个服务。详情请参阅：NOTICE。

如有 API 相关问题，请联系：[email protected]