FrankKi

FrankKi MCP

托管式远程 MCP 服务。无需安装，也无需自行托管。 将你的 Agent 指向 https://mcp.frankki.app（远程、streamable-http、OAuth 2.1 或 API 密钥）。此仓库是该服务的公开清单、文档和更新日志；服务本身为闭源，并运行在我们自己的基础设施上，因此这里没有 src/ 目录。

为 AI Agent 提供实体邮件服务。 只需调用一个工具，FrankKi MCP 就能让 Agent 向世界各地的实体地址寄送真实打印的信件。撰写、定价、寄送和追踪。文件会由全球邮政合作伙伴打印、贴上邮资并递送。

这是 FrankKi 的官方模型上下文协议（MCP）服务，面向 B2B 和开发者使用：让你的 Agent、后端和自动化工作流能够大规模地向全球寄送真实信件。

网站：frankki.app · 面向人类和 Agent 的 MCP：frankki.app/mcp（英语：frankki.app/en/mcp）

---

目录

• 什么是 FrankKi MCP？
• 为什么通过 MCP 寄送实体邮件？
• 你的 Agent 可以做什么
• 人类快速入门
• AI Agent 快速入门
• 身份验证
• 钱包和定价
• 安全性与人在回路
• 沙盒
• 合规性
• 实际寄送流程
• 发现与服务清单
• 文档
• 常见问题
• 链接

---

什么是 FrankKi MCP？

FrankKi MCP 是 FrankKi 实体邮件基础设施的 Agent 原生接口。FrankKi 负责撰写、打印并实际寄送信件。此服务将这些能力开放给软件：你的模型起草并发送一封信，随后真实文件便会送达收件人的地址。

我们通过各目的地国家/地区的邮政合作伙伴提供全球递送。这主要是一款面向 B2B 和开发者的产品：如果你正在构建需要生成并寄送实体信函的助手、运维自动化或后端，它就是你的实体输出层。

为什么通过 MCP 寄送实体邮件？

有些事情仍然必须以纸质形式送达：正式和法律通知、交易和合规邮件、合同确认、催款和提醒、客户入驻以及官方函件。这些工作流往往会卡在“现在得有人打印出来，再走到邮筒边寄出去”这一步。FrankKi MCP 可以省去这一步。同一个起草信件的 Agent 可以将其寄出、追踪递送，并覆盖全球范围。

典型用途：

• 催款和付款提醒
• 取消、终止、异议及其他正式通知
• 合同和订单确认
• 客户和账户通知
• 入驻和欢迎信
• 最后一步必须寄送实体信件的任何工作流

Agent 可以做什么

该服务提供一组专注且范围明确的工具。核心发送流程：

工具	功能	副作用
address_validate	根据目的地国家的邮政规则验证收件人地址	只读
address_search_company	按名称查询公司的邮寄地址	只读
template_list	浏览可重复使用的信件模板	只读
letter_create_draft	根据纯文本和收件人起草格式规范的信件，并返回预览	创建草稿，不发送
shipping_quote	在确认前获取寄往指定目的地的准确价格	只读
wallet_balance	查看预付钱包余额	只读
order_send	寄出一封纸质信件，并从钱包扣款；支持 maxCostEuros 限额	花费资金，邮寄纸件
order_send_batch	批量寄送：一次调用发送给多个收件人，并使用合并字段	花费资金，邮寄纸件
approval_submit	将信件提交到四眼审批队列，而不是直接发送	加入队列，不发送
order_status	跟踪信件的打印、寄出和送达状态	只读
wallet_topup_link	创建安全的 Stripe 充值链接	创建付款链接

除核心流程外，还有用于附件、信头和签名、发件人档案、发送预设、定时发送、取消订单、投递凭证（Einlieferungsbeleg）、客户端（Mandanten）查询以及 GoBD/DATEV 归档导出的工具。完整列表及其权限范围和副作用请参阅：docs/tools.md。权威且带版本的列表始终以服务器通过 MCP tools/list 方法返回的内容为准。

信件撰写以文本为先：你提供信件内容和收件人，FrankKi 会生成排版正确的文档（默认遵循 DIN 5008）。支持附件。平台有意不支持发送预先渲染的任意 PDF。

面向用户的快速入门

你无需克隆或自行托管任何内容。FrankKi MCP 服务由平台托管。将 MCP 客户端连接到该服务并完成身份验证即可。

1. 获取访问权限。 在 frankki.app/mcp 的控制面板中创建合作伙伴账户并生成密钥。为钱包充值，或先使用 沙盒（不会寄出真实邮件）。

2a. Claude Desktop 和支持原生远程连接的客户端。 添加指向该端点的自定义连接器。首次使用时，OAuth 会在浏览器中运行：

{
  "mcpServers": {
    "frankki": {
      "url": "https://mcp.frankki.app"
    }
  }
}

2b. 仅支持 stdio 的客户端（较旧版本的 Claude Desktop、部分 Cursor 配置）。使用 mcp-remote 桥接：

{
  "mcpServers": {
    "frankki": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.frankki.app"]
    }
  }
}

2c. 使用 API 密钥的无头模式（无需交互式浏览器）。将密钥作为 bearer 标头传入：

{
  "mcpServers": {
    "frankki": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.frankki.app",
        "--header", "Authorization: Bearer ${FRANKKI_API_KEY}"
      ]
    }
  }
}

2d. Claude Code。 只需一条命令：

claude mcp add --transport http frankki https://mcp.frankki.app

重启客户端后，你的模型就可以发送信件了。可以这样向它提问：“给档案中的地址发送这封付款提醒，但先告诉我价格。”

Cursor、VS Code、Windsurf、Zed、OpenAI Agents SDK 和 LangChain 的分步指南：docs/clients.md。

面向 AI Agent 的快速入门

该服务采用标准的 streamable HTTP MCP。发现方式、端点和身份验证信息汇总如下：

• 端点： https://mcp.frankki.app
• 注册名称： app.frankki/letters（已发布于 Official MCP Registry，版本 1.0.0）
• 身份验证元数据： https://mcp.frankki.app/.well-known/oauth-authorization-server（OAuth 2.1，动态客户端注册），或使用静态 bearer API 密钥
• 机器可读概览： https://frankki.app/llms.txt

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.frankki.app"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.FRANKKI_API_KEY}` } } }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

const price = await client.callTool({
  name: "shipping_quote",
  arguments: { recipientCountry: "US", deliveryType: "standard" },
});

Python

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://mcp.frankki.app"
headers = {"Authorization": f"Bearer {FRANKKI_API_KEY}"}

async with streamablehttp_client(url, headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print([t.name for t in tools.tools])

身份验证

两种模式，可按客户端选择：

• OAuth 2.1 适用于交互式客户端（Claude Desktop、IDE）。授权界面会显示 Agent 获准执行的操作，并默认授予只读权限范围。最适合最终用户连接自己的 FrankKi 账户。
• API key（Bearer token）适用于无头 Agent、服务和 CI。在控制面板中创建和轮换密钥。每个密钥都可以设置支出限额和允许使用的工具范围，因此，能够查询价格的密钥不必同时具备花钱的权限。

钱包和定价

FrankKi 使用预付钱包。你可以为钱包充值（通过 Stripe），每次寄送都会从余额中扣款。不会有意外的后付费账单，余额不足的 Agent 也无法支出。

• 定价取决于目的地国家/地区。在德国境内寄送一封普通信件，起价为 3,49 EUR；国际寄送按目的地定价。
• 目的地支持的情况下，还可选择挂号信和其他服务等级。
• 批量阶梯价格（Staffelpreise）可降低批量寄送时的每封信价格。

在调用 order_send 前，务必先调用 shipping_quote 获取实时准确价格。价格以服务端提供的数据为准，切勿将价格硬编码。

安全与人在回路

实体邮件寄出后无法撤回，且需要付费，因此平台默认采取谨慎策略：

• 如实标注。 order_send 和 order_send_batch 标注为破坏性操作；读取工具则标注为只读。Agent 可据此设置拦截条件；order_send 接受 maxCostEuros 上限，若实时价格超出该上限，就会中止寄送。
• 寄送前先审批。 寄送请求会进入审批队列。用户可通过返回的审批链接，在登录后的门户中作出决定。已准备好的 OAuth 强化机制仅允许 Agent 在获得单独、明确的自我审批授权后进行审批。请参阅授权规范和发布状态。
• 每个密钥的支出限额和工具范围。 限制自动化密钥的支出金额，并限制其可调用的工具。
• 提交前预览。 letter_create_draft 会返回排版后的预览，shipping_quote 会返回费用，因此 Agent 或人工可以在调用 order_send 前进行确认。

沙箱

无需实际寄信即可测试完整流程。在控制面板中申请一个沙箱密钥，并指向同一端点，即可获得已注资的测试钱包。内容撰写、定价和状态行为都与生产环境相同，但不会打印纸质信件，也不会扣款。端到端构建并演示集成后，再换用正式密钥。

合规性

满足企业和欧盟级需求：

• 对每次寄送进行符合 GoBD 的归档，并提供可检索的收据。
• 提供 DATEV 和通用 DMS 导出，用于会计和文档管理。
• DSGVO / GDPR：信件数据在欧盟境内处理。
• 平台和消息支持英语和德语。

实际寄送流程

1. Agent 调用 letter_create_draft，提供文本和收件人。FrankKi 会生成格式专业的文档。
2. shipping_quote 返回寄往该目的地的准确费用。Agent 或人工用户可通过审批队列进行确认。
3. order_send 将信件提交至审批队列。向用户展示审批链接；获得授权后才会履行寄送。
4. FrankKi 打印信件，并通过我们的邮政合作伙伴将其寄往全球各地。
5. 状态通过 order_status 返回：已打印、已寄出，以及在服务支持的情况下显示已送达。order_einlieferungsbeleg 会返回投递凭证。

发现与服务清单

为便于目录和注册表收录，此仓库发布了 server.json（Official MCP Registry 架构，名称为 app.frankki/letters）以及仓库级别的 llms.txt，以便 AI 辅助发现。

通过 MCP 目录找到此服务？权威信息始终以 frankki.app/mcp 为准。

文档

文档	内容
docs/tools.md	每个工具的适用范围、副作用、标准发送流程和错误代码
docs/authentication.md	OAuth 2.1、API 密钥、完整的权限范围列表和推荐配置
docs/clients.md	Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Zed、OpenAI Agents SDK、LangChain 的配置
docs/use-cases.md	催款、终止服务、合规邮件、入驻流程、Agent 原生产品
examples/	可运行的 TypeScript 和 Python 客户端（优先使用沙盒，只有在显式启用标志后才发送）

常见问题

信件真的会打印并邮寄吗，还是通过电子邮件发送？ 是纸质信件。信件会打印、贴邮资并由邮政合作伙伴投递。这不是电子邮件。

可以投递到哪些国家？ 全球范围。使用 shipping_quote 确认特定目的地是否可达以及费用。

需要自行托管服务吗？ 不需要。FrankKi 托管服务。本仓库包含文档、server.json 和示例。连接客户端或 Agent 到托管端点即可。

这是面向消费者还是企业的？ 主要面向 B2B 和开发者使用：面向需要大规模寄送实体邮件的 Agent、后端和自动化工作流。

如果我的 Agent 失控了怎么办？ 它无法超出钱包余额或密钥的消费限额；敏感信件可以强制进入人工审批队列；具有破坏性的工具也都有明确标注。请从沙盒开始。

有没有不使用 MCP 的 API？ 有，FrankKi 也提供 REST API。MCP 服务是面向 Agent 的入口。请参阅 frankki.app/mcp。

链接

• 主页： https://frankki.app
• 面向用户和 Agent 的 MCP： https://frankki.app/mcp · https://frankki.app/en/mcp
• 机器可读概览： https://frankki.app/llms.txt
• 端点： https://mcp.frankki.app
• 注册表名称： app.frankki/letters（已发布至 Official MCP Registry，版本 1.0.0）

---

由 FrankKi 团队打造：为软件提供实体邮件基础设施，让你的 Agent 和工作流无需接触打印机，即可向全球寄送真实信件。