<div align="center">
<br />
┌─────────────────────────────────────────┐
│ │
│ ██████╗ ██████╗ ███╗ ██╗███████╗ │
│ ██╔══██╗██╔═══██╗████╗ ██║██╔════╝ │
│ ██████╔╝██║ ██║██╔██╗ ██║███████╗ │
│ ██╔═══╝ ██║ ██║██║╚██╗██║╚════██║ │
│ ██║ ╚██████╔╝██║ ╚████║███████║ │
│ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝ │
│ │
└─────────────────────────────────────────┘WhatsApp in your terminal. Messages in your AI.
Bridge the WhatsApp Business Cloud API to any MCP-compatible client.<br /> Send and receive messages from Claude, Cursor, or your own tools.
pons.chat · Docs · Report Bug · Request Feature
<br />
</div>
---
The Problem
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.
What It Does
- 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
Tech Stack
| 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) |
Quick Start
Prerequisites
- Node.js 18+, pnpm
- A Meta Business App with WhatsApp Cloud API access
1. Install & configure
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:next2. Connect WhatsApp
- 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
3. Connect your AI
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"
}
}
}
}MCP Tools
| 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.
Architecture
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ │ │ │ │
│ Claude / │────▶│ Pons MCP │────▶│ Convex │
│ Cursor │ MCP │ Endpoint │ │ Backend │
│ │ │ (Next.js) │ │ │
└──────────────┘ └──────┬───────┘ └──────┬───────┘
│ │
┌──────┴───────┐ ┌──────┴───────┐
│ │ │ │
│ Pons Web │ │ Meta Graph │
│ Dashboard │ │ API v22.0 │
│ │ │ │
└──────────────┘ └──────────────┘Data Model
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)Project Structure
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)Development
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 buildDeployment
- 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)
License
MIT
---
Built by nicolaischmid.com
