# Discord Teammate — a Claude connector that pings you on Discord

This is a tiny remote MCP server. Once it's deployed and connected to Claude, any
of your scheduled runs can message you in a Discord channel when it needs a
check-in or an approval — and can read your reply back, so approvals can happen
right there in Discord.

It exposes two tools to Claude:

- **`send_discord_message`** — posts a message to your channel. With
  `urgency: "urgent"` it @-mentions you for a strong notification.
- **`read_recent_replies`** — reads the latest messages in the channel, so a
  later run can check whether you approved.

Total setup time is about 15 minutes. It runs free on Cloudflare Workers.

---

## What you'll need

- **Node 20+** on your machine (check with `node -v`).
- A **Cloudflare account** (free — you'll create it during `wrangler login` if
  you don't have one).
- A **Discord server** you own, with a channel you want the pings in. (A private
  server with one channel just for this is perfect.)

---

## Step 1 — Create the Discord bot (~5 min)

1. Go to **https://discord.com/developers/applications** → **New Application**.
   Name it something like `Claude Teammate`. Create.
2. In the left sidebar, open **Bot**.
   - Click **Reset Token**, confirm, then **Copy** the token. Keep it somewhere
     safe for a moment — this is your `DISCORD_BOT_TOKEN`.
   - Scroll down to **Privileged Gateway Intents** and turn **ON**
     **Message Content Intent**. (Needed so the bot can read your replies. If you
     only ever want one-way pings, you can skip this.)
   - Save changes.
3. In the left sidebar, open **OAuth2** → **URL Generator**.
   - Under **Scopes**, check **`bot`**.
   - Under **Bot Permissions**, check **View Channel**, **Send Messages**, and
     **Read Message History**.
   - Copy the **Generated URL** at the bottom, open it in your browser, pick your
     server, and **Authorize**. The bot is now in your server.

## Step 2 — Get your channel ID (~1 min)

1. In Discord: **User Settings → Advanced → Developer Mode → ON**.
2. Right-click the channel you want the pings in → **Copy Channel ID**. This is
   your `DISCORD_CHANNEL_ID`.
3. *(Optional, for @-mentions)* Right-click your own name → **Copy User ID**.
   This is your `DISCORD_USER_ID`.

## Step 3 — Deploy the server (~5 min)

Open a terminal in this folder and run:

```bash
npm install
npx wrangler login        # opens a browser to sign in / create a free Cloudflare account
npx wrangler deploy       # creates the Worker and prints its URL
```

The last command prints a URL like:

```
https://discord-teammate-mcp.<your-subdomain>.workers.dev
```

Copy that URL. Then set your secrets (each one uploads to the live Worker
immediately — no redeploy needed):

```bash
npx wrangler secret put DISCORD_BOT_TOKEN     # paste the bot token
npx wrangler secret put DISCORD_CHANNEL_ID    # paste the channel ID
npx wrangler secret put DISCORD_USER_ID       # optional: paste your user ID
```

*(Optional hardening — see "Security" below):*

```bash
npx wrangler secret put MCP_KEY               # paste any long random string
```

## Step 4 — Connect it to Claude (~2 min)

1. In Claude, go to **Settings → Connectors → Add custom connector**.
2. For the URL, take your Worker URL and **add `/mcp` to the end**:

   ```
   https://discord-teammate-mcp.<your-subdomain>.workers.dev/mcp
   ```

   If you set an `MCP_KEY`, add it as a query parameter:

   ```
   https://discord-teammate-mcp.<your-subdomain>.workers.dev/mcp?k=YOUR_MCP_KEY
   ```
3. Click **Add**. That's it — no OAuth needed.
4. Make sure the connector is enabled in the chat where your routines run.

## Step 5 — Test it

In a chat with the connector enabled, ask Claude:

> Send a test message to my Discord channel.

You should see it appear in the channel within a second or two. Try:

> Send an urgent Discord ping saying the deploy needs my approval.

…and confirm you get an @-mention notification.

---

## Security

By default the server is **authless**: anyone who knows the exact
`.workers.dev` URL could call it. The blast radius is small (the bot can only
post to and read the one channel you configured), but to lock it down, set an
`MCP_KEY` secret (Step 3) and append `?k=YOUR_MCP_KEY` to the connector URL
(Step 4). The Worker then rejects any request without the right key. Don't paste
the URL anywhere public either way.

## Cost

Cloudflare Workers' free plan includes 100,000 requests/day. A ping and a couple
of reply-checks per run is nowhere near that — this will stay free.

## Updating tools later

The tools live in `src/server.ts`. Edit, then run `npx wrangler deploy` again.
Claude picks up the new tool list automatically.

## Troubleshooting

- **`Method not allowed` in a browser** — expected. The `/mcp` endpoint only
  answers POST from an MCP client; visiting it in a browser (GET) returns 405.
- **Tools return "misconfigured"** — the bot token or channel ID secret isn't
  set. Re-run the `wrangler secret put` commands from Step 3.
- **`read_recent_replies` returns empty content** — enable **Message Content
  Intent** in the Discord Developer Portal (Step 1) and make sure the bot has
  **Read Message History** on the channel.
- **`403 Missing Access`** — the bot isn't in the server or can't see the
  channel. Re-run the OAuth invite from Step 1 and check channel permissions.