
hello
io.github.lakshyapocketlab/hello
Send WhatsApp messages, templates and media, and manage templates via the WhatsApp Business API.
Documentation
Hello MCP server for the WhatsApp Business API
Connect Claude, Cursor, Codex and other AI assistants to Hello, the WhatsApp Business API. Ask the assistant to list your numbers, send messages and templates, check delivery and manage templates.
This package is a small stdio MCP server for clients that cannot talk to a remote server
(Claude Desktop, some IDEs). It does not implement any tools itself: it forwards everything to the
hosted Hello MCP endpoint (https://helloapi.lakshyapocketlab.com/mcp), so the tools are always the
ones the backend serves today.
- Node.js 18 or newer
- One runtime dependency: the official
@modelcontextprotocol/sdk - Your API key is sent only as a Bearer token to the Hello endpoint. It is never logged.
Quick start
Two steps for every client:
- Get an API key. Create one (
hello_live_…) in the Hello dashboard under Integrations. - Add the server to your client, using the snippet for it below.
Claude Code connects to the hosted endpoint directly, which is the recommended setup. Clients that only speak stdio use this npm package instead.
Claude Code (recommended: remote HTTP)
claude mcp add --transport http hello https://helloapi.lakshyapocketlab.com/mcp \
--header "Authorization: Bearer hello_live_…"
Run claude mcp list to confirm the server is connected.
Claude Desktop (npx)
Edit claude_desktop_config.json (Settings, Developer, Edit Config):
{
"mcpServers": {
"hello": {
"command": "npx",
"args": ["-y", "@lakshyapocketlab/hello-mcp"],
"env": { "HELLO_API_KEY": "hello_live_…" }
}
}
}
Restart Claude Desktop. The Hello tools appear in the tools menu.
Cursor (npx)
Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects):
{
"mcpServers": {
"hello": {
"command": "npx",
"args": ["-y", "@lakshyapocketlab/hello-mcp"],
"env": { "HELLO_API_KEY": "hello_live_…" }
}
}
}
Codex (npx)
Add to ~/.codex/config.toml:
[mcp_servers.hello]
command = "npx"
args = ["-y", "@lakshyapocketlab/hello-mcp"]
env = { HELLO_API_KEY = "hello_live_…" }
Codex can also use the hosted endpoint directly: set url = "https://helloapi.lakshyapocketlab.com/mcp" and bearer_token_env_var = "HELLO_API_KEY".
Setup
Requirements
- Node.js 18 or newer, for
npxor a global install. - A Hello API key. The server reads it from
HELLO_API_KEYin its environment and sends it only as a Bearer token to the Hello endpoint.
Configuration
| Setting | Default | Description |
|---|---|---|
HELLO_API_KEY | required | Your Hello API key. The server exits with an error on stderr if it is missing. |
HELLO_MCP_URL | https://helloapi.lakshyapocketlab.com/mcp | MCP endpoint to proxy to. |
--url <url> | Same as HELLO_MCP_URL; wins over it. Must be http or https. | |
--help, --version | Print usage or the version and exit. |
To point the server at another endpoint, such as a local or staging deployment, set HELLO_MCP_URL in the client's env block, or pass --url:
HELLO_API_KEY=hello_live_… npx @lakshyapocketlab/hello-mcp --url http://localhost:8080/mcp
Logs go to stderr only, because stdout carries the MCP stream.
Tools
The server exposes the tools of the hosted endpoint, so the list is always the one the backend serves. These are the tools it provides today.
| Tool | What it does |
|---|---|
ping | Checks that the API key works. |
list_phone_numbers | Lists the sending numbers with their phone_number_id and waba_id, and whether each can send. Call it first if you do not know these IDs. |
send_message | Sends a WhatsApp message in Cloud API format (text, template, media, interactive, reaction, ...), or marks a received message as read. Real and billed. |
get_message_status | Gets a sent message by its ID: queued, sent, delivered, read or failed. |
upload_media | Uploads a file (about 7 MB) for a media message or template header, and returns a media ID. |
list_templates | Lists a WhatsApp Business Account's templates, filtered by status, category or language. Paged. |
get_template | Gets one template with its components and {{variables}}. |
create_template | Submits a new template to Meta for review. |
create_templates_bulk | Creates or edits up to 100 templates in one call. |
edit_template | Edits an approved, rejected or paused template. It goes back to review. |
sync_templates | Re-reads every template of the account from Meta. |
delete_template | Permanently deletes one language of a template. Destructive. |
delete_templates_by_name | Permanently deletes every language of a template name. Destructive. |
get_webhook_override | Shows whether a number's webhook is overridden to the user's own URL, and that override's status. |
set_webhook_override | Points a number's webhook at the user's own URL. Hello stops showing that number's incoming messages and statuses. |
remove_webhook_override | Removes the direct webhook, so Hello receives the number's events again. |
reapply_webhook_override | Applies a stored direct webhook on Meta again, when its status is draft. |
The server also provides get_guide, with reference topics messages (message formats), templates, errors (error codes and fixes) and direct_webhook.
Messages are real and billed, and the delete tools are permanent. Free-form messages need an open 24-hour window with the recipient; otherwise the assistant should send an approved template. set_webhook_override changes where a number's events go, so the assistant should confirm it with you first.
Troubleshooting
| Symptom | Fix |
|---|---|
HELLO_API_KEY is not set | Add the key to the server's env block and restart the client. For the Claude Code HTTP setup, re-run claude mcp add with the --header value. |
Invalid MCP URL or must be http or https | Check HELLO_MCP_URL or --url. The value must be a full http:// or https:// URL, normally ending in /mcp. |
Unknown argument | The server accepts only --url, --help and --version. |
could not connect to <url> | Check your network, proxy or firewall, and that the URL is reachable from this machine. |
| Authentication errors from a tool | The key is wrong or has been revoked. Create a new key in the dashboard and update the client's configuration. |
| Tools do not appear in Claude Desktop | Check that the JSON is valid, then quit Claude Desktop completely and reopen it. |
npx fails to start the server | Check the Node version with node --version; it must be 18 or newer. Run npx -y @lakshyapocketlab/hello-mcp --version in a terminal to see the error. |
A send fails with error code 131047 | The recipient has not messaged the number in the last 24 hours. Send an approved template instead. |
If none of these apply, contact support@lakshyapocketlab.com and include the FBTrace ID from the error, if one is shown.
How it works
MCP client ──stdio──▶ hello-mcp ──Streamable HTTP + Bearer key──▶ https://helloapi.lakshyapocketlab.com/mcp
initialize, tools/list and tools/call (plus prompts and resources if the remote advertises them) are forwarded unchanged, and errors from the remote reach your client as-is. Nothing is reimplemented locally, so the tool list and results never drift from the hosted endpoint.
Links
- Docs: lakshyapocketlab.com/docs, including the MCP integration guide
- SDKs: hello-node, hello-python, hello-go
- Examples: hello-examples
- Support: support@lakshyapocketlab.com
- CONTRIBUTING.md · SECURITY.md · CHANGELOG.md
License
MIT, Copyright Lakshya Pocket Lab.
No installation packages available.