# Discord MCP Server for VS Code

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets VS Code Copilot (or any MCP-compatible agent) send and receive Discord messages **as your own user account** — enabling real-time testing of Discord bot commands directly from your editor.

> **⚠️ Discord ToS Notice:** Automating a user account ("self-botting") is against Discord's Terms of Service. This tool is intended **strictly for local development/testing of your own bots on your own servers**. Do not use it for spam, abuse, or on servers you don't control. Use at your own risk.

---

## Why a user account?

Many bot commands check server state tied to the command invoker — e.g., `message.member.voice.channel` to verify the user is in a voice channel before playing audio. A separate bot account cannot satisfy these checks. Messages **must** originate from your real Discord user to test these commands properly.

---

## Prerequisites

- **Node.js 18+** (uses native `fetch`)
- **VS Code** with GitHub Copilot (or another MCP host like Claude Desktop / Cursor)
- **Your Discord user token** (see below)

### Obtaining your Discord user token

1. Open Discord in a browser or the desktop app
2. Open Developer Tools (`F12` / `Ctrl+Shift+I`)
3. Go to the **Network** tab
4. Perform any action in Discord (send a message, switch channels)
5. Find any request to `discord.com/api`
6. Copy the `Authorization` header value — that's your user token

> Your user token grants full access to your Discord account. Treat it like a password and **never commit it to version control**.

---

## Installation

```bash
# 1. Clone the repository
git clone https://github.com/masonbesmer/code-discord-mcp.git
cd code-discord-mcp

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Set your Discord user token
cp .env.example .env
# Edit .env and set DISCORD_USER_TOKEN=your-token-here
```

---

## VS Code Integration

The repository includes `.vscode/mcp.json` which automatically registers the server with VS Code. The server reads your token from the `DISCORD_USER_TOKEN` environment variable.

Make sure the variable is set in your shell **before** launching VS Code:

```bash
# macOS / Linux
export DISCORD_USER_TOKEN="your-token-here"
code .

# Windows PowerShell
$env:DISCORD_USER_TOKEN = "your-token-here"
code .
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `send_message` | Send a text message to a Discord channel |
| `read_messages` | Read recent messages from a channel |
| `wait_for_response` | Send a command and wait for a bot response |
| `list_channels` | List channels in a guild |
| `list_guilds` | List guilds your account is in |
| `delete_message` | Delete a message (with confirmation prompt) |

### Available Resources

| Resource | Description |
|----------|-------------|
| `discord://guild/{guildId}/channels` | Channel list for a guild |
| `discord://channel/{channelId}/recent` | Last 25 messages in a channel |

---

## Example Workflow

1. Open your Discord bot project in VS Code
2. Start a Copilot Chat session in **Agent Mode**
3. Ask: _"Send `!help` to my #bot-testing channel and show me what my bot responds with"_
4. Copilot will:
   - Call `list_guilds` to find your server
   - Call `list_channels` to find `#bot-testing`
   - Call `wait_for_response` with `!help`
   - Show you the bot's response inline in the chat

---

## Development

```bash
# Watch mode (recompiles on file changes)
npm run dev

# Run tests
npm test

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## Security

| Concern | Mitigation |
|---------|-----------|
| Token exposure | Read from env var only; never logged or returned in responses; `.env` in `.gitignore` |
| Discord ToS | Local dev/testing on your own servers only |
| Rate limiting | Automatic retry after `retry_after` on HTTP 429; 500ms polling interval |
| Accidental pings | `allowed_mentions: { parse: [] }` prevents @everyone/@here pings |
| Destructive actions | `delete_message` has `destructiveHint: true` — VS Code shows a confirmation dialog |
| Stdout pollution | All diagnostic output goes to stderr; stdout is reserved for MCP JSON-RPC |

---

## Dependencies

| Package | Purpose |
|---------|---------|
| `@modelcontextprotocol/sdk` | MCP server framework (stdio transport, tool registration) |
| `zod` | Input schema validation |
| `typescript` _(dev)_ | TypeScript compiler |
| `@types/node` _(dev)_ | Node.js type definitions |
| `vitest` _(dev)_ | Test runner |

> **No Discord library needed.** All Discord API calls use Node 18+ native `fetch`.