<div align="center">

# Sinores MCP WhatsApp

### A self-hosted WhatsApp gateway for AI agents

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

[![GitHub stars](https://img.shields.io/github/stars/karl4th/sinores-wp-mcp?style=flat&logo=github&label=Stars&color=18181b)](https://github.com/karl4th/sinores-wp-mcp/stargazers)
[![MIT License](https://img.shields.io/badge/License-MIT-22c55e?style=flat)](./LICENSE)
[![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-339933?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-7c3aed?style=flat)](https://modelcontextprotocol.io/)

[Get started](#quick-start) · [Connect an agent](#connect-an-ai-agent) · [How it works](#how-it-works) · [Configuration](#configuration)

</div>

---

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](https://nodejs.org/) 22 or newer
- A WhatsApp account that can link a companion device

### 1. Install

```bash
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

```bash
openssl rand -hex 32
```

Add the generated value to `.env.local`:

```dotenv
ADMIN_TOKEN=your-generated-token
```

### 3. Start Sinores

```bash
npm run dev
```

Open [http://localhost:3000](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**

<details>
<summary><strong>Production-style local run</strong></summary>

```bash
npm run build
npm start
```

</details>

## Connect an AI agent

Sinores exposes a Streamable HTTP MCP endpoint at:

```text
http://localhost:3000/api/mcp
```

Add the endpoint and admin token to your MCP client:

```json
{
  "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

```mermaid
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")]
```

Sinores keeps the entire stack deliberately small:

- [Next.js](https://nextjs.org/) serves the dashboard, REST routes, and MCP endpoint.
- [Baileys](https://github.com/WhiskeySockets/Baileys) manages WhatsApp companion-device sessions.
- [SQLite](https://sqlite.org/) stores channels and message history in `./data`.
- The [Model Context Protocol SDK](https://modelcontextprotocol.io/) 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`](./.env.example) for a ready-to-copy configuration file.

## Open source or hosted

| | Sinores Open | [Sinores Cloud](https://sinores.net) |
|---|---|---|
| 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](https://github.com/karl4th/sinores-wp-mcp/issues).

If Sinores helps you build something useful, consider [starring the repository](https://github.com/karl4th/sinores-wp-mcp). It helps other developers discover the project.

## License

Distributed under the [MIT License](./LICENSE).

---

<div align="center">

Built for developers connecting AI agents to the real world.

[Website](https://sinores.net) · [Report a bug](https://github.com/karl4th/sinores-wp-mcp/issues) · [Give it a star](https://github.com/karl4th/sinores-wp-mcp)

</div>