Getting Started

Get Discord Agent MCP running in under 10 minutes. This guide walks you through creating a Discord bot, configuring the server, and connecting to Claude.

Prerequisites

Before you begin, make sure you have:

Step 1: Create a Discord Bot

First, create a Discord application and bot in the Discord Developer Portal.

1.1 Create Application

  1. Go to the Discord Developer Portal
  2. Click “New Application”
  3. Enter a name (e.g., “My Server Bot”) and click Create

1.2 Create Bot User

  1. In the left sidebar, click “Bot”
  2. Click “Add Bot” and confirm
  3. Under the bot’s username, click “Reset Token”
  4. Copy the token and save it securely - you’ll need this later

Important: Never share your bot token publicly. Treat it like a password.

1.3 Enable Required Intents

Still on the Bot page, scroll down to “Privileged Gateway Intents” and enable:

Click “Save Changes”.

1.4 Invite Bot to Your Server

  1. Go to OAuth2 > URL Generator in the sidebar
  2. Under Scopes, select:
    • bot
    • applications.commands
  3. Under Bot Permissions, select the permissions you need, or choose Administrator for full access:
    • Manage Channels
    • Manage Roles
    • Manage Messages
    • Read Messages/View Channels
    • Send Messages
    • Manage Threads
    • Moderate Members
  4. Copy the generated URL at the bottom
  5. Open the URL in your browser
  6. Select your server and click Authorize

Step 2: Install Discord Agent MCP

2.1 Clone the Repository

git clone https://github.com/aj-geddes/discord-agent-mcp.git
cd discord-agent-mcp

2.2 Install Dependencies

npm install

2.3 Configure Environment

cp .env.example .env

Edit .env and add your bot token:

DISCORD_TOKEN=your_bot_token_here
TRANSPORT_MODE=http
HTTP_PORT=3000
LOG_LEVEL=info
LOG_FORMAT=json

2.4 Build and Start

# Build the TypeScript
npm run build

# Start the server
npm start

You should see:

{"level":"info","message":"Starting Discord MCP Server","version":"2.0.2"}
{"level":"info","message":"Discord client connected successfully"}
{"level":"info","message":"MCP Server running on http://localhost:3000/mcp"}

Step 3: Connect to Claude Code

With the server running, open a new terminal:

claude mcp add --transport http discord-agent http://localhost:3000/mcp

Verify the connection:

claude mcp list
# Should show: discord-agent: http://localhost:3000/mcp (HTTP)

Option B: Project Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "discord-agent": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Step 4: Start Using It!

Open Claude Code and try these commands:

"List all channels in my server"

"Create a new text channel called #announcements"

"Send a welcome message to the general channel"

Claude will use the Discord Agent MCP tools to execute these actions on your server.

Verify Everything Works

Test the Health Endpoint

curl http://localhost:3000/health

Should return:

{"status":"healthy","discord":"connected"}

Test Tool Listing

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Should return a list of 71 tools.

Configuration Options

Variable Default Description
DISCORD_TOKEN Required Your Discord bot token
TRANSPORT_MODE http http or stdio
HTTP_PORT 3000 Server port
LOG_LEVEL info debug, info, warn, error
LOG_FORMAT json json or pretty

Development Mode

For development with auto-reload:

npm run dev

The server will automatically restart when you make changes.

Next Steps

Common Setup Issues

Bot Not Connecting

Tools Not Working

Claude Code Can’t Connect

Full Troubleshooting Guide →