Sinores MCP WhatsApp

A self-hosted WhatsApp gateway for AI agents

Connect a WhatsApp number to any MCP-compatible agent.
Send messages, read history, and manage channels from one local application.

Get started · Connect an agent · How it works · Configuration

---

Sinores Open turns a WhatsApp number into tools that AI agents and applications can use. It combines a web dashboard, REST API, MCP server, WhatsApp connection, and local database in a single Node.js application.

One process. One port. No Docker, Postgres, or Redis required.

Features

	Capability	What it gives you
🤖	MCP server	Connect Codex, Claude, or any MCP-compatible agent
💬	Messaging	Send and receive WhatsApp text messages
🗂️	Message history	Read locally stored conversations with filters
📱	Channel management	Link WhatsApp numbers using the familiar QR flow
🖥️	Web dashboard	Manage channels, inspect status, and test messages
🔌	REST API	Integrate WhatsApp into backends and scripts
💾	Local persistence	Keep data and sessions on your own machine with SQLite
🔐	Simple authentication	Protect the dashboard and APIs with one admin token

Quick start

Requirements

• Node.js 22 or newer
• A WhatsApp account that can link a companion device

1. Install

git clone https://github.com/karl4th/sinores-wp-mcp.git
cd sinores-wp-mcp
npm install
cp .env.example .env.local

2. Create an admin token

openssl rand -hex 32

Add the generated value to .env.local:

ADMIN_TOKEN=your-generated-token

3. Start Sinores

npm run dev

Open http://localhost:3000, sign in with your admin token, and create a channel. Then scan its QR code from:

WhatsApp → Linked devices → Link a device

Production-style local run

npm run build
npm start

Connect an AI agent

Sinores exposes a Streamable HTTP MCP endpoint at:

http://localhost:3000/api/mcp

Add the endpoint and admin token to your MCP client:

{
  "mcpServers": {
    "sinores": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

The agent receives four tools:

Tool	Description
list_channels	List connected channels and their current status
get_channel_status	Get the state of a specific channel
send_message	Send a text message to a phone number
list_messages	Read message history with direction and timestamp filters

Start with list_channels to get a channelId, then use that ID with the other tools.

How it works

flowchart LR
    Agent["AI agent"] -->|"MCP over HTTP"| Sinores["Sinores Open"]
    App["Your application"] -->|"REST API"| Sinores
    Dashboard["Web dashboard"] --> Sinores
    Sinores --> WhatsApp["WhatsApp via Baileys"]
    Sinores --> Database[("SQLite")]

Loading

Sinores keeps the entire stack deliberately small:

• Next.js serves the dashboard, REST routes, and MCP endpoint.
• Baileys manages WhatsApp companion-device sessions.
• SQLite stores channels and message history in ./data.
• The Model Context Protocol SDK exposes agent tools from the same application.

Configuration

Variable	Required	Default	Purpose
ADMIN_TOKEN	Yes	—	Protects the dashboard, REST API, and MCP endpoint
CHANNEL_LIMIT	No	10	Maximum number of WhatsApp channels
DATA_DIR	No	./data	Location of the SQLite database and application data
BAILEYS_AUTH_DIR	No	./data/baileys-auth	Location of WhatsApp session credentials
COOKIE_SECURE	No	unset	Set to true when serving the application over HTTPS

See .env.example for a ready-to-copy configuration file.

Open source or hosted

	Sinores Open	Sinores Cloud
Best for	Developers, prototypes, personal automation	Teams and production workloads
Hosting	Your machine or server	Managed for you
Database	Local SQLite	Managed infrastructure
Authentication	Single admin token	Multi-tenant access controls
Operations	You maintain it	Sinores maintains it
License	MIT	Commercial service

Security

• Treat ADMIN_TOKEN as a password. Anyone who has it can access every connected channel.
• Never commit .env.local, the data directory, or Baileys session credentials.
• Use HTTPS and set COOKIE_SECURE=true when exposing an instance outside your local network.
• Use a separate WhatsApp number for automation whenever possible.

Warning

Sinores uses Baileys, an unofficial WhatsApp Web API. It is not affiliated with or endorsed by WhatsApp or Meta. Automated activity may lead to account restrictions. Review WhatsApp's terms and use the project responsibly.

Contributing

Issues and pull requests are welcome. If you found a bug, have an idea, or built something interesting with Sinores, open an issue.

If Sinores helps you build something useful, consider starring the repository. It helps other developers discover the project.

License

Distributed under the MIT License.

---

Built for developers connecting AI agents to the real world.

Website · Report a bug · Give it a star