FrankKi MCP server
Commit Oct 31, 2026Allows AI agents to compose, print, and send real physical letters to any address worldwide via a hosted MCP server.
Also known as datPascal/frankki-mcp, frankki-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Oct 31, 2026
- License
- MIT
What is FrankKi MCP?
FrankKi allows AI agents to compose, print, and send real physical letters to any address worldwide via a hosted MCP server.
Summary generated from the project's README
About FrankKi MCP server
FrankKi MCP provides a remote, hosted interface that enables AI agents to manage physical mail delivery worldwide. Instead of requiring local installation or self-hosting, developers connect their agents to a streamable HTTP endpoint. This server allows software to bridge the gap between digital workflows and physical correspondence by composing, printing, and mailing real documents to any global address.
Designed for B2B and developer use, the server includes tools for validating recipient addresses, searching for company locations, and generating shipping quotes. Agents can create professional letter drafts, manage bulk mailings via batch commands, and track delivery status. To ensure financial control, the system operates on a prepaid wallet model where users top up funds via Stripe. Security is managed through OAuth 2.1 for interactive desktop clients or API keys for headless automation, allowing for specific tool scopes and spending limits to prevent unauthorized costs.
What you can do with it
- 1Automated payment remindersAn agent can identify overdue accounts and send physical dunning letters to customers.
- 2Address verification and pricingAn AI can check if a mailing address is valid and calculate the exact postage cost before committing to a send.
Written from the project's README. Every use case is checked against a quote from it.
How to install FrankKi MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall FrankKi MCP in Claude Code
$ claude mcp add --transport http frankki-mcp https://mcp.frankki.app/Install FrankKi MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"frankki-mcp": {
"url": "https://mcp.frankki.app/"
}
}
}Install FrankKi MCP in VS Code
.vscode/mcp.json
{
"servers": {
"frankki-mcp": {
"type": "http",
"url": "https://mcp.frankki.app/"
}
}
}Install FrankKi MCP in VS Code CLI
$ code --add-mcp '{"name":"frankki-mcp","type":"http","url":"https://mcp.frankki.app/"}'Install FrankKi MCP in Codex
$ codex mcp add frankki-mcp --url https://mcp.frankki.app/Install FrankKi MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.frankki-mcp] url = "https://mcp.frankki.app/"
Install FrankKi MCP in Gemini CLI
$ gemini mcp add -s user --transport http frankki-mcp https://mcp.frankki.app/Install FrankKi MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"frankki-mcp": {
"url": "https://mcp.frankki.app/",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledatpascal/frankki-mcp is public and reachablegithub.com/datpascal/frankki-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/datpascal/frankki-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 614 msPass
README
View on GitHubFrankKi MCP
Hosted, remote MCP server. Nothing to install, nothing to self-host. Point your agent at https://mcp.frankki.app (remote, streamable-http, OAuth 2.1 or API key). This repository is the public manifest, documentation and changelog for that server; the server itself is closed-source and runs on our own infrastructure, which is why there is no src/ directory here.
Physical mail for AI agents. With one tool call, FrankKi MCP lets an agent send a real, printed letter to a physical address anywhere in the world. Compose, price, send, and track. The document is printed, franked, and delivered by postal partners worldwide.
This is the official Model Context Protocol (MCP) server for FrankKi. It is built for B2B and developer use: give your agents, backends, and automated workflows the ability to put real letters in the mail, at scale, worldwide.
Website: frankki.app · MCP for humans and agents: frankki.app/mcp (English: frankki.app/en/mcp)
Contents
- What is FrankKi MCP?
- Why physical mail via MCP?
- What your agent can do
- Quick start for humans
- Quick start for AI agents
- Authentication
- Wallet and pricing
- Safety and human-in-the-loop
- Testing without mailing
- Compliance
- How a send actually works
- Discovery and server manifest
- Documentation
- FAQ
- Links
What is FrankKi MCP?
FrankKi MCP is the agent-native interface to FrankKi's physical mail infrastructure. FrankKi composes, prints, and physically mails letters. This server exposes that capability to software: your model drafts a letter and sends it, and a real document arrives at the recipient's address.
Delivery is worldwide, handled by our postal partners in each destination country. It is primarily a B2B and developer product: if you are building an assistant, an ops automation, or a backend that needs to produce and dispatch physical correspondence, this is your physical-output layer.
Why physical mail via MCP?
Some things still have to arrive on paper: formal and legal notices, transactional and compliance mail, contract confirmations, dunning and reminders, customer onboarding, official correspondence. These workflows usually dead-end at "now a human prints this and walks to a postbox." FrankKi MCP removes that step. The same agent that drafts the letter can send it, worldwide, and track delivery.
Typical uses:
- Dunning and payment reminders
- Cancellations, terminations, objections, and other formal notices
- Contract and order confirmations
- Customer and account notifications
- Onboarding and welcome letters
- Any workflow whose last step must be a physical letter
What your agent can do
The server exposes a focused, scoped tool set. The core send flow:
| Tool | What it does | Side effect |
|---|---|---|
address_validate |
Validate a recipient address against destination-country postal rules | read only |
address_search_company |
Look up a company's postal address by name | read only |
template_list |
Browse reusable letter templates | read only |
letter_create_draft |
Draft a professionally formatted letter from plain text plus a recipient, returns a preview | creates a draft, no send |
shipping_quote |
Get the exact price for a send to a given destination before committing | read only |
wallet_balance |
Read the prepaid wallet balance | read only |
order_send |
Send one physical letter, charges the wallet; supports a maxCostEuros guard |
spends money, mails paper |
order_send_batch |
Bulk send: one call, many recipients with merge fields | spends money, mails paper |
approval_submit |
Route a letter into the four-eyes approval queue instead of sending directly | queues, no send |
order_status |
Track a letter through printed, posted, and delivered | read only |
wallet_topup_link |
Create a secure Stripe top-up link | creates a payment link |
Beyond the core flow there are tools for attachments, letterheads and signatures, sender profiles, send presets, scheduled sends, order cancellation, posting receipts (Einlieferungsbeleg), client (Mandanten) lookups, and GoBD/DATEV archive exports. The full list with scopes and side effects: docs/tools.md. The authoritative, versioned list is always what the server returns from the MCP tools/list method.
By default you provide the letter content and the recipient, and FrankKi lays out the document to DIN 5008. Attachments are supported. A finished letter PDF of your own also works: letter_upload_pdf checks that the address sits where the post reads it, and order_send with pdfStorageKey sends it unchanged.
Quick start for humans
You do not clone or self-host anything. The FrankKi MCP server is hosted. You point your MCP client at it and authenticate.
1. Get access. Create a partner account and issue a key from the dashboard at frankki.app/mcp. Fund your wallet (top-ups from 10 to 500 EUR each). You can test without mailing anything first.
2a. Claude (claude.ai and Claude Desktop) and clients with native remote support. Add a custom connector: Customize > Connectors > "+ Add" > "Add custom connector", name it FrankKi, URL https://mcp.frankki.app, then under Authentication choose "Sign in now". OAuth runs in your browser: sign in with your FrankKi account or create one there. Claude Code:
claude mcp add --transport http frankki https://mcp.frankki.app
Then run /mcp in Claude Code to sign in.
2b. Clients that only speak stdio (older Claude Desktop, some Cursor setups). Bridge with mcp-remote:
{
"mcpServers": {
"frankki": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.frankki.app"]
}
}
}
2c. Headless with an API key (no interactive browser). Pass the key as a bearer header:
{
"mcpServers": {
"frankki": {
"command": "npx",
"args": [
"-y", "mcp-remote", "https://mcp.frankki.app",
"--header", "Authorization: Bearer ${FRANKKI_API_KEY}"
]
}
}
}
2d. Claude Code. One command:
claude mcp add --transport http frankki https://mcp.frankki.app
Restart the client, and your model can now send letters. Ask it something like: "Send this payment reminder to the address on file, but show me the price first."
Step-by-step guides for Cursor, VS Code, Windsurf, Zed, the OpenAI Agents SDK, and LangChain: docs/clients.md.
Quick start for AI agents
The server is standard streamable HTTP MCP. Discovery, endpoint, and auth in one place:
- Endpoint:
https://mcp.frankki.app - Registry name:
app.frankki/letters(published in the Official MCP Registry, version 1.0.0) - Auth metadata:
https://mcp.frankki.app/.well-known/oauth-authorization-server(OAuth 2.1, dynamic client registration) or a static bearer API key - Machine-readable overview:
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])
Authentication
Two modes, pick per client:
- OAuth 2.1 for interactive clients (Claude Desktop, IDEs). The consent screen shows what the agent is allowed to do, and read-only scopes are granted by default. Best when an end user connects their own FrankKi account.
- API key (bearer token) for headless agents, servers, and CI. Issue and rotate keys in the dashboard. Each key can carry a spending limit and an allowed-tools scope, so a key that may look up prices does not have to be a key that may spend money.
Wallet and pricing
FrankKi runs on a prepaid wallet. You top it up (via Stripe), and each send draws from the balance. No surprise post-paid invoices, and an out-of-credit agent simply cannot spend.
- Pricing depends on the destination country and your monthly volume. A standard black-and-white letter within Germany costs 1,99 EUR below 20 letters a month, then 1,89 EUR from 20, 1,79 EUR from 100, 1,69 EUR from 500 and 1,59 EUR from 1,000 letters a month (the reached tier applies to every letter that month). International sends are priced per destination.
- Top-ups are 10 to 500 EUR each. The balance does not expire and there is no subscription.
- FrankKi is a small business under § 19 UStG and shows no VAT: the price you see is the final price.
- Registered mail and other service levels are available where the destination supports them.
- Volume tiers (Staffelpreise) reduce the per-letter price at scale.
Always call shipping_quote for the live, exact figure before order_send. Prices are authoritative from the server, never hardcode them.
Safety and human-in-the-loop
Sending physical mail is irreversible and costs money, so the platform is cautious by default:
- Honest annotations.
order_sendandorder_send_batchare annotated as destructive; read tools as read-only. Your agent can gate on this, andorder_sendaccepts amaxCostEuroscap that aborts the send if the live price exceeds it. - Approval before dispatch. Sends enter the approval queue. The user decides in the signed-in portal through the returned approval link. The prepared OAuth hardening allows agent approval only after a separate, explicit self-approval grant. See the authorization contract and release status.
- Per-key spending limits and tool scopes. Cap what an automated key can spend, and restrict which tools it may call.
- Preview before commit.
letter_create_draftreturns a rendered preview andshipping_quotereturns the cost, so an agent or a human can confirm beforeorder_send.
Testing without mailing
Regular accounts have no separate sandbox. Drafts, previews, quotes and order_send with dryRun: true are free: you get the rendered pages and the exact price, nothing is printed and nothing is charged. A dry run needs a sender profile and the signed data processing agreement (AVV), the same as a real send. Only a letter you approve draws from your wallet.
Compliance
Enterprise and EU-grade, for teams that need it:
- GoBD-compliant archiving of every send, with retrievable receipts.
- DATEV and generic DMS exports for accounting and document management.
- DSGVO / GDPR: letter data is processed in the EU.
- Platform and messages available in English and German.
How a send actually works
- Your agent calls
letter_create_draftwith the text and a recipient. FrankKi renders a professionally formatted document. shipping_quotereturns the exact cost for that destination. The agent, or a human via the approval queue, confirms.order_sendqueues the letter for approval. Show its approval link to the user; fulfillment follows an authorized decision.- FrankKi prints the letter and hands it off for delivery worldwide via our postal partners.
- Status flows back through
order_status: printed, posted, and, where supported, delivered.order_einlieferungsbelegreturns the posting receipt.
Discovery and server manifest
For directories and registries, this repo publishes server.json (Official MCP Registry schema, name app.frankki/letters) and a repo-level llms.txt for AI-assisted discovery.
Found this server through an MCP directory? The canonical source of truth is always frankki.app/mcp.
Documentation
| Doc | Contents |
|---|---|
| docs/tools.md | Every tool with scope, side effects, the canonical send flow, and error codes |
| docs/authentication.md | OAuth 2.1, API keys, the full scope list, recommended setups |
| docs/clients.md | Setup for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, OpenAI Agents SDK, LangChain |
| docs/use-cases.md | Dunning, terminations, compliance mail, onboarding, agent-native products |
| examples/ | Runnable TypeScript and Python clients (dry run first, send behind an explicit flag) |
FAQ
Is the letter really printed and mailed, or is it email? Real paper. It is printed, franked, and delivered by postal partners. This is not email.
Which countries can it deliver to?
Worldwide. Use shipping_quote to confirm reach and cost for a specific destination.
Do I host the server?
No. FrankKi hosts it. This repo is documentation, server.json, and examples. You connect a client or agent to the hosted endpoint.
Is this for consumers or businesses? Primarily B2B and developer use: agents, backends, and automated workflows that need to dispatch physical mail at scale.
What if my agent goes rogue? It cannot spend beyond the wallet balance or a key's spending limit, sensitive letters can be forced through a human approval queue, and destructive tools are clearly annotated. Start with a dry run.
Is there an API without MCP? Yes, FrankKi also exposes a REST API. The MCP server is the agent-native front door. See frankki.app/mcp.
Links
- Homepage: https://frankki.app
- MCP for humans and agents: https://frankki.app/mcp · https://frankki.app/en/mcp
- Machine-readable overview: https://frankki.app/llms.txt
- Endpoint: https://mcp.frankki.app
- Registry name:
app.frankki/letters(published in the Official MCP Registry, version 1.0.0)
Built by the team behind FrankKi: physical mail infrastructure for software, so your agents and workflows can send real letters worldwide without ever touching a printer.
FrankKi MCP questions
How do I add FrankKi MCP to Claude Code?
Run claude mcp add --transport http frankki-mcp https://mcp.frankki.app/ in your terminal. Add --scope user to make it available in every project.
How do I add FrankKi MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How much does it cost to send a letter?
Pricing depends on the destination country and volume. In Germany, a standard black-and-white letter starts at 1,99 EUR and decreases with higher monthly volumes.
Can I test the service without actually mailing anything?
Yes, you can use drafts, previews, quotes, and the order_send tool with the dryRun parameter set to true for free.
Is there a way to prevent an agent from spending too much money?
Yes, the order_send tool accepts a maxCostEuros guard, and you can also set per-key spending limits and tool scopes in the dashboard.