discord-integration

name	discord-integration
version	1.0.1
description	Use when sending Discord messages or encountering bot permission errors - provides three-tier integration methods with automatic fallback (MCP → REST API → Gateway); prevents wasted time on OAuth scope issues
triggers	["discord","send message","permission error","bot access","discord.js","mcp discord"]

Discord Integration

Comprehensive skill for working with Discord from Claude Code using multiple methods with automatic fallback.

When to Use This Skill

Use this skill when the user wants to:

• Send messages to Discord channels
• Read messages from Discord channels
• Troubleshoot Discord bot connection or permission issues
• Set up or configure Discord bot access
• Choose the best method for Discord interaction

Trigger phrases:

• "Send a message to Discord"
• "Post to #channel-name"
• "Read messages from Discord"
• "Discord bot isn't working"
• "Can't access Discord channel"

When NOT to Use This Skill

Do NOT use this skill for:

• Discord server management - Use Discord's admin panel for creating channels, managing roles, or configuring server settings
• Complex bot features - For advanced slash commands, persistent state, or complex workflows, build a dedicated bot application
• Real-time message listening - This skill focuses on sending/reading; continuous message monitoring requires a persistent Gateway connection outside this skill's scope
• Voice channel interactions - This skill only handles text channels

Available Bots on This Machine

1. Sombra (Local MCP Bot)

• Purpose: Claude Code MCP integration (this machine only)
• Token Location: ~/.claude/discordmcp/.env
• Client ID: 1435274653126889544
• Guild: Nice Wolf Studio (745376918030909471)
• Connection: discord.js Gateway via MCP server
• Use For: Claude Code sessions, automated workflows

2. GladOSv3 (tjr-suite Bot)

• Purpose: Trading bot application
• Token Location: ~/Dev/tjr-suite/.env
• Client ID: 1425850836277395506
• Guild: Nice Wolf Studio (745376918030909471)
• Connection: discord.js Gateway (always running)
• Use For: Trading signals, slash commands, application-specific tasks

Important: These are separate bots. Do not confuse their configurations.

Three Integration Methods (Priority Order)

Method 1: MCP Tools (PREFERRED)

Availability: After Claude Code full restart Tools: mcp__discord__send-message, mcp__discord__read-messages

Pros:

• Clean, native Claude Code integration
• No manual script execution
• Persistent connection via discord.js Gateway
• Smart auto-discovery (find channels by name or ID)

Cons:

• Requires full Claude Code restart to load
• Not available immediately after config changes

Method 2: Discord.js Gateway Script (FALLBACK)

Availability: Always (if bot token configured) Script: ~/.claude/discordmcp/send-test-message.js

Pros:

• Works immediately, no restart needed
• Direct access to discord.js library
• Can be customized easily
• Reliable connection

Cons:

• Requires manual script execution
• Less integrated than MCP tools

Method 3: REST API (LAST RESORT)

Availability: Always Method: Direct curl to Discord API v10

Pros:

• No dependencies
• Quick for testing

Cons:

• Often gets "Missing Access" (OAuth scope issues)
• Requires exact permissions
• Less reliable than Gateway methods

Integration Method Selection (MANDATORY)

ALWAYS follow this priority order - do NOT skip steps:

User requests Discord interaction
  ↓
STEP 1: Are MCP tools available? (mcp__discord__send-message)
  YES → REQUIRED: Use MCP tools (Method 1)
  NO ↓
  ↓
STEP 2: Can we use send-test-message.js? (file exists, token configured)
  YES → REQUIRED: Use Gateway script (Method 2)
  NO ↓
  ↓
STEP 3: Try REST API (Method 3) with warning about limitations
  ↓
FALLBACK LOGIC:
  - If Method 1 fails → Immediately try Method 2
  - If Method 2 fails → Try Method 3
  - If Method 3 fails → Report error with troubleshooting steps

CRITICAL: You MUST attempt Method 1 (MCP) first, even if you think it won't work. Only fall back after confirming failure.

Step-by-Step Instructions

Step 1: Check Method Availability

Before attempting any Discord interaction, determine which method is available:

1. Try MCP tools first:

   // Attempt to use MCP tool
   mcp__discord__send-message({
     channel: "CHANNEL_ID",
     message: "Test"
   })
   

   If you get "No such tool available" error → MCP not loaded

2. Fall back to Gateway script:

   # Check if script exists
   ls -la ~/.claude/discordmcp/send-test-message.js
   
   # Check if token configured
   grep DISCORD_TOKEN ~/.claude/discordmcp/.env
   

3. REST API as last resort (expect permission issues)

Step 2: Execute Based on Available Method

Using Method 1: MCP Tools

Send Message:

mcp__discord__send-message({
  channel: "1420759585349697710",  // Channel ID or name
  message: "Your message here"
})

Read Messages:

mcp__discord__read-messages({
  channel: "1420759585349697710",
  limit: 10  // 1-100
})

Using Method 2: Gateway Script

Send Message:

cd ~/.claude/discordmcp
node send-test-message.js CHANNEL_ID "Optional custom message"

# Example:
node send-test-message.js 1420759585349697710 "Hello from Claude Code"

Custom Message: Create a modified version of the script or pass message as argument.

Using Method 3: REST API

Send Message:

curl -X POST "https://discord.com/api/v10/channels/CHANNEL_ID/messages" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Your message"}'

Note: Will likely fail with "Missing Access" - see troubleshooting.

Step 3: Handle Errors

See troubleshooting section below for specific error codes and solutions.

Red Flags - STOP

If you encounter these situations, STOP and address them immediately:

❌ Skipping MCP method without trying first

• Why it's bad: MCP is the most reliable method; skipping wastes time with inferior fallbacks
• Fix: Always attempt mcp__discord__send-message before assuming it won't work

❌ Not checking bot permissions before sending

• Why it's bad: Results in repeated "Missing Access" errors and wasted API calls
• Fix: Verify bot has "View Channel" and "Send Messages" permissions first

❌ Retrying same failed method repeatedly

• Why it's bad: Same input = same output; you're wasting time and rate limits
• Fix: After one failure, switch to next method in priority order

❌ Missing token/credentials setup

• Why it's bad: Nothing will work without valid authentication
• Fix: Verify token exists in appropriate .env file and test with /users/@me endpoint

❌ Not handling 403 Forbidden errors properly

• Why it's bad: 403 means permission issue, not connection issue
• Fix: Check channel-specific permissions or switch to Gateway method (better permission handling)

❌ Using REST API when Gateway methods are available

• Why it's bad: REST API has OAuth scope limitations that cause "Missing Access" errors
• Fix: Use MCP tools or Gateway script instead - they have proper intents

Verification Checklist

Before marking Discord integration as complete, verify:

• MCP tools attempted first - You tried mcp__discord__send-message before other methods
• Permissions verified for channel - Bot has "View Channel" and "Send Messages" in target channel
• Message sent successfully - Received confirmation (not just "no error")
• Error handling implemented - Code handles failures gracefully with fallback or clear error message
• Correct bot used - Sombra for MCP/local, GladOSv3 for tjr-suite (not mixed up)
• Token validated - Tested token with /users/@me endpoint returns valid bot info

Prerequisites

General Requirements

• Bot must be in the target Discord server
• Bot must have proper permissions in the target channel
• Valid bot token must be configured

For MCP Tools

• Claude Code must be fully restarted after mcp.json changes
• MCP server must be configured in ~/.claude/mcp.json
• Discord MCP server must be built: cd ~/.claude/discordmcp && npm run build

For Gateway Script

• Node.js installed
• discord.js package available (in discordmcp directory)
• Token in ~/.claude/discordmcp/.env

For REST API

• DISCORD_BOT_TOKEN environment variable set
• Bot must have been added with proper OAuth2 scopes

Troubleshooting

Error: "No such tool available: mcp__discord__send-message"

Cause: Discord MCP server not loaded in Claude Code.

Solutions:

1. Verify MCP configuration exists:

   grep -A 5 '"discord"' ~/.claude/mcp.json
   

   Should show:

   "discord": {
     "type": "stdio",
     "command": "node",
     "args": ["/Users/USERNAME/.claude/discordmcp/build/index.js"]
   }
   

2. Verify MCP server is built:

   ls -la ~/.claude/discordmcp/build/index.js
   

3. Test MCP server manually:

   cd ~/.claude/discordmcp
   node build/index.js
   

   Should see: "Discord bot is ready!" and "Discord MCP Server running on stdio"

4. Fully restart Claude Code:

   • Quit completely (Cmd+Q or equivalent)
   • Relaunch application
   • Start new session

5. If still not available, use Method 2 (Gateway script) instead.

Error: "Missing Access" (Code 50001)

Cause: Bot doesn't have permission to access that channel.

Solutions:

1. Verify bot is in the server:

   curl -H "Authorization: Bot TOKEN" \
     https://discord.com/api/v10/users/@me/guilds
   

2. Check channel-specific permissions:

   • Right-click channel in Discord
   • Edit Channel → Permissions
   • Add the bot (Sombra or GladOSv3)
   • Enable: View Channel, Send Messages, Read Message History

3. Grant server-wide permissions:

   • Server Settings → Roles
   • Find bot's role
   • Enable Send Messages permission

4. If using REST API, switch to Gateway method (discord.js or MCP tools)

Error: "Unknown Guild" (Code 10004)

Cause: Bot is not in that Discord server.

Solutions:

1. Verify bot membership:

   curl -H "Authorization: Bot TOKEN" \
     https://discord.com/api/v10/users/@me/guilds
   

2. Invite bot to server using OAuth2 URL:

   For Sombra (Local MCP):

   https://discord.com/api/oauth2/authorize?client_id=1435274653126889544&permissions=69632&scope=bot
   

   For GladOSv3 (tjr-suite):

   https://discord.com/api/oauth2/authorize?client_id=1425850836277395506&permissions=69632&scope=bot
   

3. After inviting, wait a few seconds for bot to join

4. Verify the bot appears in server member list

Error: Connection Timeout or "Discord bot is ready!" but MCP fails

Cause: Token invalid or bot permissions insufficient.

Solutions:

1. Verify token is correct:

   curl -H "Authorization: Bot TOKEN" \
     https://discord.com/api/v10/users/@me
   

   Should return bot user info, not error.

2. Check token hasn't been regenerated:

   • Go to Discord Developer Portal
   • Applications → Your Bot → Bot
   • If token was regenerated, update configs

3. Verify bot has proper Gateway intents:

   • In Developer Portal: Bot → Privileged Gateway Intents
   • Enable: Guilds, Guild Messages (Message Content if reading)

4. Check .env file syntax:

   cat ~/.claude/discordmcp/.env
   

   No extra spaces, quotes, or newlines around token.

Error: "Channel not found or not a text channel"

Cause: Invalid channel ID or bot can't see it.

Solutions:

1. Verify channel ID is correct:

   • Right-click channel in Discord
   • Copy Channel ID (enable Developer Mode if needed)
   • Channel IDs are 17-19 digit numbers

2. Check bot can see the channel:

   • Bot must have "View Channel" permission
   • Channel must not be in a category the bot can't access

3. Try using channel name instead of ID (if using MCP tools):

   mcp__discord__send-message({
     channel: "bot-testing-grounds",  // Name instead of ID
     message: "Test"
   })
   

Bot Configuration Reference

Sombra (Local MCP) Configuration

Files:

• Token: ~/.claude/discordmcp/.env
• MCP Config: ~/.claude/mcp.json (lines 55-61)
• Source: ~/.claude/discordmcp/src/index.ts
• Built: ~/.claude/discordmcp/build/index.js

Environment Variables:

DISCORD_TOKEN=MTQzNTI3NDY1MzEyNjg4OTU0NA...
DISCORD_CLIENT_ID=1435274653126889544
DISCORD_GUILD_ID=745376918030909471
DISCORD_ENABLED=true

Rebuild after changes:

cd ~/.claude/discordmcp
npm run build

GladOSv3 (tjr-suite) Configuration

Files:

• Token: ~/Dev/tjr-suite/.env
• Source: ~/Dev/tjr-suite/packages/app/src/services/discord/
• HTTP API: Running on http://localhost:3000

Environment Variables:

DISCORD_TOKEN=MTQyNTg1MDgzNjI3NzM5NTUwNg...
DISCORD_CLIENT_ID=1425850836277395506
DISCORD_GUILD_ID=745376918030909471
DISCORD_ENABLED=true

Note: GladOSv3 is always running as part of tjr-suite. Do not confuse with Sombra.

Common Channel IDs

Nice Wolf Studio Server:

• Guild ID: 745376918030909471
• #bot-testing-grounds: 1420759585349697710

Permission Reference

Required Bot Permissions

Minimum (for message sending):

• View Channels (1024)
• Send Messages (2048)

Recommended:

• Read Message History (65536)
• Add Reactions (64)

Permission Integer: 69632 (includes all recommended)

How to Calculate Custom Permissions

Visit: https://discordapi.com/permissions.html

Enter desired permissions, copy the integer for OAuth2 URL.

Testing Checklist

When setting up or troubleshooting Discord integration:

• Bot token is valid (test with /users/@me endpoint)
• Bot is in the correct server (check /users/@me/guilds)
• Bot has View Channel permission
• Bot has Send Messages permission in target channel
• Channel ID is correct (17-19 digit number)
• Token configured in correct .env file
• MCP server built (if using MCP tools)
• Claude Code restarted (if using MCP tools)

Quick Reference Commands

Verify Token

curl -H "Authorization: Bot TOKEN" https://discord.com/api/v10/users/@me

List Guilds

curl -H "Authorization: Bot TOKEN" https://discord.com/api/v10/users/@me/guilds

Test MCP Server

cd ~/.claude/discordmcp && node build/index.js

Send via Gateway Script

cd ~/.claude/discordmcp && node send-test-message.js CHANNEL_ID "Message"

Check MCP Config

grep -A 5 '"discord"' ~/.claude/mcp.json

Examples

See examples.md in this skill directory for complete working examples.

Related Documentation

• Setup Guide: ~/.claude/discordmcp/SETUP_COMPLETE.md
• Validation Report: ~/.claude/discordmcp/VALIDATION_REPORT.md
• Gateway Script: ~/.claude/discordmcp/send-test-message.js
• Discord.js Docs: https://discord.js.org/
• Discord API: https://discord.com/developers/docs

---

After Using This Skill

REQUIRED NEXT STEPS:

1. Verify message sent successfully - Check verification checklist (6 items) to confirm integration worked
2. Document method used - Record which method succeeded (MCP/Gateway/REST) for future reference
3. Test error handling - Verify fallback logic works if primary method fails

OPTIONAL NEXT STEPS:

• Set up logging - Track Discord API calls, errors, and response times for debugging
• Create reusable wrapper - Build abstraction around working method for consistent usage
• Monitor bot health - Set up alerts for token expiration or permission changes

---

Changelog

Version 1.0.1 (2025-11-14)

• Added superpowers-style improvements for better agent guidance
• Added "When NOT to Use" section to prevent misuse
• Enhanced Integration Method Selection with MANDATORY fallback logic
• Added "Red Flags - STOP" section with 6 common anti-patterns
• Added "Verification Checklist" for completion validation
• Improved frontmatter with version, triggers, and clearer description
• Updated description to emphasize automatic fallback and OAuth scope issue prevention

Version 1.0.0 (Initial)

• Initial discord-integration skill
• Three-tier integration methods (MCP, Gateway, REST API)
• Comprehensive troubleshooting for common errors
• Configuration reference for Sombra and GladOSv3 bots