┌─────────────────────────────────────────┐
│ │
│ ██████╗ ██████╗ ███╗ ██╗███████╗ │
│ ██╔══██╗██╔═══██╗████╗ ██║██╔════╝ │
│ ██████╔╝██║ ██║██╔██╗ ██║███████╗ │
│ ██╔═══╝ ██║ ██║██║╚██╗██║╚════██║ │
│ ██║ ╚██████╔╝██║ ╚████║███████║ │
│ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝ │
│ │
└─────────────────────────────────────────┘
WhatsApp in your terminal. Messages in your AI.
Bridge the WhatsApp Business Cloud API to any MCP-compatible client.
Send and receive messages from Claude, Cursor, or your own tools.
pons.chat · Docs · Report Bug · Request Feature
WhatsApp Business has a powerful API, but it's locked behind REST calls, webhook plumbing, and token management. There's no way to plug it into the tools you actually use — AI assistants, dev environments, automation pipelines.
Pons (Latin for "bridge") connects WhatsApp to the Model Context Protocol, so your AI assistant can read, search, and send WhatsApp messages as naturally as it reads files or searches the web.
- Full WhatsApp inbox — real-time web UI with conversations, media, delivery receipts
- MCP server — expose WhatsApp as tools for Claude Desktop, Cursor, or any MCP client
- Multi-tenant — multiple WhatsApp Business Accounts, multiple users per account
- Media handling — images, videos, documents auto-downloaded to Convex storage (Meta URLs expire in 5 min)
- 24h window tracking — know when you can send free-form vs. template-only messages
- API key management — scoped keys for different clients with expiration
| Layer | Choice |
|---|---|
| Framework | Next.js 16 (App Router, Turbopack) |
| Backend | Convex (database, auth, file storage, scheduled actions) |
| Auth | Convex Auth (Google OAuth) |
| MCP | @modelcontextprotocol/sdk — Streamable HTTP transport |
| UI | shadcn/ui + Tailwind CSS v4 |
| Domain | pons.chat |
| Hosting | Vercel (FRA1) + Convex Cloud (eu-west-1) |
- Node.js 18+, pnpm
- A Meta Business App with WhatsApp Cloud API access
git clone https://github.com/NicolaiSchmid/pons.git
cd pons
pnpm install
# Start Convex dev (opens browser for auth on first run)
npx convex dev
# In another terminal
pnpm run dev:next- Create a Meta Business App → add WhatsApp product → get test phone number
- Sign in to Pons at
http://localhost:3000 - Create an Account with your WABA ID, Phone Number ID, Access Token, and App Secret
- Set webhook URL in Meta to
https://your-domain.com/api/webhook - Use the generated Webhook Verify Token to verify
Go to API Keys in the dashboard, create a key, and add to your MCP config:
{
"mcpServers": {
"pons": {
"url": "https://your-pons-domain.com/api/mcp",
"headers": {
"Authorization": "Bearer pons_your_api_key_here"
}
}
}
}| Tool | Scope | Description |
|---|---|---|
list_conversations |
read | List recent conversations with preview |
get_conversation |
read | Get full conversation with messages |
search_messages |
read | Search messages by content |
send_text |
send | Send a text message |
send_template |
send | Send a template message (for closed windows) |
list_templates |
read | List available message templates |
mark_as_read |
write | Mark conversation as read |
send_reaction |
write | React to a message with emoji |
Scopes: read (view), write (mark read, react), send (send messages). Assign per key.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ │ │ │ │
│ Claude / │────▶│ Pons MCP │────▶│ Convex │
│ Cursor │ MCP │ Endpoint │ │ Backend │
│ │ │ (Next.js) │ │ │
└──────────────┘ └──────┬───────┘ └──────┬───────┘
│ │
┌──────┴───────┐ ┌──────┴───────┐
│ │ │ │
│ Pons Web │ │ Meta Graph │
│ Dashboard │ │ API v22.0 │
│ │ │ │
└──────────────┘ └──────────────┘
Account (WhatsApp Business Account)
├── AccountMember (owner / admin / member)
├── Contact (customer phone numbers)
│ └── Conversation (thread with a contact)
│ └── Message (text, media, location, reaction...)
├── Template (pre-approved message templates)
├── ApiKey (scoped MCP authentication)
└── WebhookLog (raw payloads for debugging)
pons/
├── convex/ # Backend
│ ├── schema.ts # Database schema
│ ├── auth.ts # Convex Auth (Google OAuth)
│ ├── accounts.ts # Account + member management
│ ├── conversations.ts # Conversation queries
│ ├── messages.ts # Message CRUD
│ ├── mcp.ts # MCP queries + API key management
│ ├── mcpNode.ts # Crypto operations (Node.js runtime)
│ ├── webhook.ts # Webhook ingestion + media download
│ └── whatsapp.ts # Meta Graph API actions
├── src/
│ ├── app/
│ │ ├── api/mcp/ # MCP HTTP endpoint
│ │ ├── api/webhook/ # WhatsApp webhook handler
│ │ └── page.tsx # Landing + auth gate
│ ├── components/
│ │ ├── Dashboard.tsx # Main shell
│ │ ├── ConversationList.tsx # Sidebar
│ │ ├── MessageThread.tsx # Chat view
│ │ ├── AccountSettings.tsx # Settings + member management
│ │ ├── ApiKeyManager.tsx # API key CRUD
│ │ ├── AccountSelector.tsx # Account switcher
│ │ └── SetupAccount.tsx # Onboarding
│ └── components/ui/ # shadcn/ui primitives
├── middleware.ts # Auth middleware (webhook excluded)
└── vercel.json # Vercel config (FRA1 region)
pnpm dev # Convex + Next.js in parallel
pnpm run check:write # Biome lint + format (auto-fix)
pnpm run typecheck # TypeScript check
pnpm run build # Production build- Connect GitHub repo to Vercel
- Set environment variables:
NEXT_PUBLIC_CONVEX_URL,CONVEX_DEPLOY_KEY - Build command is pre-configured:
pnpm convex deploy --cmd 'pnpm run build' - Disable Vercel Deployment Protection for production (webhook needs unauthenticated access)
MIT
Built by nicolaischmid.com