# Neuron MCP Server

> WhatsApp automation platform with 300+ MCP tools for AI-powered chatbots, broadcasts, campaigns, and more.

[![npm version](https://img.shields.io/npm/v/neuron-mcp-server)](https://www.npmjs.com/package/neuron-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![smithery badge](https://smithery.ai/badge/rsh/neuron)](https://smithery.ai/servers/rsh/neuron)

## What is Neuron?

[Neuron](https://neuron.ng) is an AI-powered WhatsApp automation platform. This MCP server exposes **300+ tools** that let AI coding assistants — Claude Code, Cursor, Windsurf, and other MCP-compatible clients — manage your entire WhatsApp business programmatically.

Build chatbots, send broadcasts, manage contacts, create campaigns, publish newsletters, and more — all through natural language with your AI assistant.

## Quick Start

### Option 1: Remote Server (Recommended — zero install)

Add to your MCP client config:

```json
{
  "mcpServers": {
    "neuron": {
      "type": "url",
      "url": "https://mcp.neuron.ng/mcp"
    }
  }
}
```

No installation required. Works immediately with any MCP client that supports Streamable HTTP.

### Option 2: Local Server (via npm)

Run directly with npx:

```bash
npx neuron-mcp-server
```

Or install globally:

```bash
npm install -g neuron-mcp-server
```

Claude Code config (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "neuron": {
      "command": "npx",
      "args": ["-y", "neuron-mcp-server"]
    }
  }
}
```

## Authentication

Three ways to authenticate:

### 1. Browser Login (Recommended)

Call `neuron_login()` with no arguments. The server returns a URL — open it in your browser to authorize securely. No credentials are shared with the AI.

### 2. MCP Token

Generate a token from your Neuron dashboard (**Settings > MCP Tokens**), then:

```
neuron_login({ token: "your-mcp-token" })
```

### 3. Environment Variable

Set `NEURON_AUTH_TOKEN` for unattended/CI use:

```bash
NEURON_AUTH_TOKEN=your-token npx neuron-mcp-server
```

## Available Tools (300+)

| Category | Tools | Description |
|----------|-------|-------------|
| **Authentication** | 9 | Login, register, org switching, token refresh |
| **Bot Management** | 11 | Create and manage AI chatbots with configurable LLM models |
| **Conversations & Messaging** | 20 | Message management, human takeover, send WhatsApp messages, polls |
| **Approvals** | 5 | Human-in-the-loop approve/reject over WhatsApp |
| **Channels & Sessions** | 19 | WhatsApp connections, QR/pair-code, session management |
| **Social Channels** | 11 | Post to X, Instagram, Facebook, LinkedIn, TikTok |
| **Broadcasts** | 7 | Bulk messaging to contact lists |
| **Campaigns** | 16 | Sponsored campaigns, marketplace, funding |
| **List Campaigns** | 8 | Paced, per-run messaging to list members |
| **Contacts** | 12 | CRUD, import/export, semantic search, sync |
| **Contact Lists** | 11 | Segmentation, merge, membership management |
| **Leads** | 7 | Multi-source lead capture, pool, convert |
| **Knowledge Bases** | 14 | Upload documents, semantic search, sync, ingest content |
| **Newsletters** | 9 | WhatsApp Channel/newsletter management |
| **Products & Sales** | 17 | Sell products, checkout, orders, delivery, memberships |
| **Flows** | 11 | Event-driven automation flows and runs |
| **Tasks & Scheduling** | 12 | Scheduled autonomous bot tasks and messages |
| **Personas** | 9 | Build and apply voice personas |
| **Group Management** | 11 | Create groups, manage members, settings |
| **Webhooks** | 10 | Inbound and outbound webhook management |
| **Custom Tools** | 10 | HTTP API tools for bots with secret injection |
| **Bot API** | 8 | Bot-scoped API keys, chat and messaging |
| **Marketplace & Pool** | 23 | Publish and install bots, tools, and contact lists |
| **Blog** | 6 | Content publishing |
| **Organizations & Audit** | 11 | Team management, audit logs, member invitations |
| **Billing & Wallet** | 12 | Subscriptions, wallet, payouts, bank accounts |
| **Profile & Privacy** | 10 | Profile name/status/picture, privacy settings |
| **Reflections** | 4 | Self-learning bot improvement suggestions |
| **Media & AI** | 2 | Upload media, AI text rewriting |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `NEURON_API_URL` | API base URL | `https://api.neuron.ng/api/v1` |
| `NEURON_AUTH_TOKEN` | Pre-set auth token | — |
| `MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |
| `PORT` | HTTP server port (when using `http` transport) | `3001` |

## IDE Setup

### Claude Code

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "neuron": {
      "command": "npx",
      "args": ["-y", "neuron-mcp-server"]
    }
  }
}
```

Or use the remote server:

```json
{
  "mcpServers": {
    "neuron": {
      "type": "url",
      "url": "https://mcp.neuron.ng/mcp"
    }
  }
}
```

### Cursor

**Settings > MCP Servers > Add Streamable HTTP**

URL: `https://mcp.neuron.ng/mcp`

### Windsurf

**Settings > AI > MCP Servers > Add**

Use either the remote URL or local npx command.

## Development

```bash
git clone https://github.com/conquext/neuron-mcp-server.git
cd neuron-mcp-server
npm install
npm run dev
```

## Links

- **Website:** [neuron.ng](https://neuron.ng)
- **Documentation:** [neuron.ng/docs](https://neuron.ng/docs)
- **MCP Server Docs:** [neuron.ng/docs/mcp-server](https://neuron.ng/docs/mcp-server)
- **npm:** [npmjs.com/package/neuron-mcp-server](https://www.npmjs.com/package/neuron-mcp-server)

Free to start — no credit card required.

## License

[MIT](LICENSE)