Konnect

WhatsApp Konnco MCP — a native macOS app that bridges your WhatsApp account into Claude as an MCP server. Pair once, click once, done.

Built by Konnco Studio. Inspired by the brand mantra: Execute Better.

---

What it is

A .app bundle for macOS (Apple Silicon + Intel) that:

1. Pairs your personal WhatsApp via QR or 8-digit pairing code (using the unofficial multi-device protocol via whatsmeow).
2. Runs a local HTTP server only reachable on 127.0.0.1.
3. Ships with a tiny stdio MCP shim (konnect-mcp) bundled in Konnect.app/Contents/MacOS/.
4. Writes itself into Claude Desktop's MCP config with one click.
5. Lives in the menu bar so it can keep ingesting messages even when the window is closed.

                                ┌──────────────────────────────────────┐
                                │              Konnect.app              │
   Claude Desktop  ─stdio──►   konnect-mcp  ─HTTP─►   Konnect (Wails)
                                │                       │              │
                                │                       └─ whatsmeow ──┼──► WhatsApp
                                │                       └─ SQLite      │
                                │                       └─ menu bar    │
                                └──────────────────────────────────────┘

Prerequisites

OS	macOS 11+ (built and tested on M1 Pro)
Go	1.23+
Wails CLI	go install github.com/wailsapp/wails/v2/cmd/wails@latest
Phone	A WhatsApp account you can pair (preferably not your primary number)

⚠️ Use a secondary number. WhatsApp's TOS doesn't permit unofficial clients. Risk is small but non-zero — don't link a number you can't afford to lose.

Install (one click)

The friendliest path: double-click Install Konnect.command from Finder. It opens Terminal, builds everything, codesigns, copies to /Applications/, and launches Konnect — all in one go.

Prefer the terminal? Same thing:

cd Konnect
./install.sh             # interactive (asks before /Applications/ + launch)
./install.sh --yes       # non-interactive — does it all
./install.sh --build-only  # build only, leave the .app in build/bin/
./install.sh --arm64     # M-series only, ~2× faster than universal

Or for CI / scripted builds without prompts, the lower-level builder still works:

PLATFORM=darwin/arm64 ./build/build.sh

The output is build/bin/Konnect.app (or /Applications/Konnect.app if you let the installer move it).

First run

1. Launch Konnect from /Applications (or with open build/bin/Konnect.app).
2. The window shows a QR code. On your phone open WhatsApp → Settings → Linked Devices → Link a Device → scan.
3. After pairing, the view flips to "You're live" with the MCP server info.
4. Click Connect to Claude. Konnect writes itself into ~/Library/Application Support/Claude/claude_desktop_config.json.
5. Restart Claude Desktop. The whatsapp MCP server should appear.

That's it.

Can't scan the QR?

In the same screen, type your phone number (digits only, with country code, no +) and click Generate pairing code. Enter the 8-digit code in WhatsApp → Linked Devices → Link with phone number.

What Claude can do once connected

Twelve tools are exposed via MCP:

Tool	Purpose
wa_status	Connection + pairing health
wa_pair_code	Programmatic pairing for unattended setups
wa_list_chats	Recent chats (filterable)
wa_get_messages	Read messages from a chat
wa_search_messages	FTS5 full-text search
wa_list_contacts	Search contacts
wa_mark_read	Mark a chat as read
wa_send_text	Send a text
wa_send_media	Send image/video/audio/document
wa_download_media	Save received media to disk
wa_create_group	New group with initial members
wa_update_group_participants	Add / remove / promote / demote

JIDs accepted in either form: 628123@s.whatsapp.net, xxx@g.us, or bare phone digits — Konnect normalizes.

Confirm before sending

In Settings (or the menu bar), toggle "Confirm before sending". With it on, every outgoing wa_send_* call from Claude pops a Konnect confirmation dialog — you click Approve or Deny before the message hits WhatsApp's servers. Off by default for fluency.

Where things live

~/Library/Application Support/Konnect/
├── session.db        # whatsmeow's signal session (do NOT share — it IS your account)
├── messages.db       # local cache: chats, messages, FTS index, contacts
├── settings.json     # confirm-before-send, port, etc.
└── media/            # files saved by wa_download_media

Delete session.db to force a re-pair.

Project layout

Konnect/
├── main.go                    # Wails entry, embeds frontend
├── wails.json                 # Wails project config
├── go.mod
├── app/                       # Core Go package
│   ├── app.go                 # Wails-bound App struct
│   ├── whatsapp.go            # whatsmeow service
│   ├── store.go               # SQLite cache
│   ├── http_server.go         # localhost REST consumed by the shim
│   ├── send.go                # text + media + downloads
│   ├── settings.go            # persisted user settings
│   ├── claude_integrate.go    # writes claude_desktop_config.json
│   ├── menubar.go             # macOS menu bar (fyne.io/systray)
│   ├── qr.go                  # render pairing QR as PNG data URL
│   ├── icon-tray.png          # menu bar template icon (22×22)
│   └── util*.go
├── frontend/                  # Branded UI (Konnco palette, Montserrat)
│   ├── index.html
│   ├── style.css
│   ├── app.js
│   └── assets/
│       ├── logo.svg
│       └── logogram.svg
├── mcp-shim/                  # The konnect-mcp binary Claude Desktop spawns
│   ├── main.go
│   └── go.mod
└── build/
    ├── build.sh               # produces .app bundle (universal)
    └── darwin/Info.plist      # bundle metadata, LSUIElement, etc.

Brand notes

UI palette is the official Konnco Studio brand:

• Konnco Orange #E86B18 — primary
• Konnco Black #252629 — secondary
• Konnco White #F9F9F9 — surface
• Montserrat 400/500/600/700/800

Konnect's own mark (the small chat-bubble-with-eye in the corner) is a Konnect mark — not a modification of the Konnco logo, per the brand rules at brand.konnco.com.

Troubleshooting

App shows "damaged" / can't open — Konnect is built unsigned by default. Right-click the .app → Open → Open. Or sign with your Developer ID.

go mod tidy fails on whatsmeow — make sure you're on Go 1.23+. The whatsmeow tree pulls in features only available there.

Claude Desktop doesn't show the WhatsApp tools — restart Claude after clicking Connect to Claude. The MCP servers are loaded only at startup. Check ~/Library/Application Support/Claude/claude_desktop_config.json to confirm the entry was written.

Pairing code expired / QR timed out — they auto-refresh; the UI shows a small status. If it stalls, click Logout from WhatsApp (if visible) or delete ~/Library/Application Support/Konnect/session.db and relaunch.

"Konnect unreachable" errors from Claude — the app needs to be running. The shim talks to it on http://127.0.0.1:8765.

Caveats

• WhatsApp ships only a partial recent history to a freshly linked device. Older chats become searchable as new messages arrive.
• This is research/personal-use software. Don't use it to spam — anti-abuse heuristics will ban the linked number quickly.
• The HTTP API is bound to 127.0.0.1 only; never expose it externally.

License

Internal Konnco project. Inquire before redistributing.