# neuron

A Discord [MCP](https://modelcontextprotocol.io) server that gives AI agents full control of a Discord bot — messages, channels, roles, threads, forums, events, webhooks, reactions, moderation, image generation, and real-time voice.

Built with [Bun](https://bun.sh), [discord.js](https://discord.js.org), and the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).

## Features

- **Messaging** — send, edit, delete, pin, bulk-delete, fetch history, wait for new events in real time
- **Channels & threads** — create/edit/delete channels, threads, and forum posts
- **Server management** — roles, members, invites, webhooks, scheduled events, moderation (kick/ban/timeout)
- **Voice** — join voice channels, speak with ElevenLabs TTS, or run a full conversational voice agent that listens and replies
- **Images** — generate images with OpenAI and post them straight to a channel
- **Event streaming** — `discord_wait_for_events` blocks until new messages/reactions/etc. arrive, so an agent can run a continuous listen-and-respond loop

## Setup

1. Create a bot in the [Discord Developer Portal](https://discord.com/developers/applications), enable the **Message Content**, **Server Members**, and **Presence** privileged intents as needed, and invite it to your server.

2. Install dependencies:

   ```sh
   bun install
   ```

3. Configure credentials:

   ```sh
   cp .env.example .env
   # then fill in DISCORD_BOT_TOKEN (required) and the optional keys
   ```

   | Variable | Required | Purpose |
   | --- | --- | --- |
   | `DISCORD_BOT_TOKEN` | yes | Bot token for the Discord API |
   | `ELEVENLABS_API_KEY` | for voice | TTS and the conversational voice agent |
   | `ELEVENLABS_VOICE_ID` | no | Voice to speak with (has a default) |
   | `OPENAI_API_KEY` | for images | `discord_generate_image` |
   | `IMAGE_OUTPUT_DIR` | no | Where to save generated images |

## Usage

The server speaks MCP over stdio. Point any MCP client at it — for example, with Claude Code:

```sh
claude mcp add discord -- bun run /path/to/neuron/src/index.ts
```

Or in an `mcpServers` config:

```json
{
  "mcpServers": {
    "discord": {
      "command": "bun",
      "args": ["run", "/path/to/neuron/src/index.ts"]
    }
  }
}
```

You can also run it directly to check that it starts:

```sh
bun start
```

## Tools

<details>
<summary>All 57 tools</summary>

**Messages** — `discord_send_message`, `discord_get_message`, `discord_get_messages`, `discord_edit_message`, `discord_delete_message`, `discord_bulk_delete_messages`, `discord_pin_message`, `discord_unpin_message`, `discord_get_pinned_messages`, `discord_wait_for_events`

**Reactions** — `discord_add_reaction`, `discord_remove_reaction`, `discord_get_reactions`

**Channels & threads** — `discord_get_channel`, `discord_get_channels`, `discord_create_channel`, `discord_edit_channel`, `discord_delete_channel`, `discord_create_thread`, `discord_delete_thread`, `discord_archive_thread`, `discord_unarchive_thread`, `discord_add_thread_member`, `discord_remove_thread_member`, `discord_create_forum_post`

**Guilds & members** — `discord_get_guild`, `discord_get_guilds`, `discord_get_member`, `discord_get_members`, `discord_get_user`, `discord_kick_member`, `discord_ban_member`, `discord_timeout_member`

**Roles** — `discord_get_roles`, `discord_create_role`, `discord_edit_role`, `discord_delete_role`, `discord_add_role`, `discord_remove_role`

**Invites & webhooks** — `discord_get_invites`, `discord_create_invite`, `discord_delete_invite`, `discord_create_webhook`, `discord_send_webhook_message`, `discord_delete_webhook`

**Events** — `discord_get_events`, `discord_create_event`, `discord_delete_event`

**Voice** — `discord_join_voice`, `discord_leave_voice`, `discord_speak`, `discord_get_voice_status`, `discord_get_voice_members`, `discord_start_voice_agent`, `discord_stop_voice_agent`, `discord_get_voice_agent_status`

**Misc** — `discord_generate_image`, `discord_set_avatar`

</details>

## License

[MIT](LICENSE)