README.md•6.34 kB
# Discord MCP Server with Bearer Token Authentication
A secure Discord MCP (Model Context Protocol) server that provides Discord integration tools with JWT Bearer Token authentication.
## 🔐 Security Features
- **Bearer Token Authentication** using JWT tokens
- **Discord token protection** - tokens are embedded in JWT claims, not passed as parameters
- **Audit logging** - all tool calls are logged with user information
- **Temporary bot connections** - no persistent Discord bot instances
- **RSA key pair encryption** for token signing and verification
## 📋 Available Tools
| Tool | Description |
|------|-------------|
| `send_message` | Send messages to Discord channels |
| `get_messages` | Fetch recent messages from channels |
| `get_channel_info` | Get channel metadata and information |
| `search_messages` | Search for messages containing keywords |
| `moderate_content` | Delete specific messages from channels |
## 🚀 Setup and Installation
### Prerequisites
- Python 3.8+
- Discord bot token with appropriate permissions
- Virtual environment (recommended)
### Installation
1. **Install dependencies** (already installed in your venv):
```bash
pip install discord.py fastapi fastmcp uvicorn python-dotenv PyJWT
```
2. **Create a Discord bot** and get your bot token:
- Go to [Discord Developer Portal](https://discord.com/developers/applications)
- Create a new application and bot
- Copy the bot token
- Invite the bot to your server with necessary permissions
3. **Set up environment variables** (optional):
```bash
# Create .env file
echo "DISCORD_TOKEN=your_discord_bot_token_here" > .env
```
## 🏃♂️ Running the Server
### Start the Server
```bash
python app.py
```
The server will start on `http://localhost:8000` and display:
- Available tools
- Authentication information
- Token generation instructions
### Generate Access Token
Replace `YOUR_DISCORD_TOKEN` with your actual Discord bot token:
```bash
python -c "from app import generate_access_token; print(generate_access_token('YOUR_DISCORD_TOKEN'))"
```
## 🔧 Using the Server
### Authentication
All requests must include a JWT Bearer token in the Authorization header:
```
Authorization: Bearer <your_jwt_token>
```
### Making Tool Calls
**Endpoint**: `POST /mcp/v1/tools/invoke`
**Headers**:
```
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
```
**Request Format**:
```json
{
"method": "tool_name",
"params": {
"parameter1": "value1",
"parameter2": "value2"
}
}
```
### Examples
#### Get Channel Information
```bash
curl -X POST http://localhost:8000/mcp/v1/tools/invoke \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"method": "get_channel_info",
"params": {
"channel_id": "1234567890123456789"
}
}'
```
#### Send a Message
```bash
curl -X POST http://localhost:8000/mcp/v1/tools/invoke \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"method": "send_message",
"params": {
"channel_id": "1234567890123456789",
"message": "Hello from MCP server!"
}
}'
```
#### Search Messages
```bash
curl -X POST http://localhost:8000/mcp/v1/tools/invoke \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"method": "search_messages",
"params": {
"channel_id": "1234567890123456789",
"query": "hello",
"limit": 10
}
}'
```
## 🧪 Testing
Use the provided test script to verify your setup:
```bash
# Update YOUR_DISCORD_TOKEN in test_server.py first
python test_server.py
```
## 📊 Monitoring and Logs
- **Audit logs** are written to `audit.log`
- **Server logs** are displayed in the console
- Each tool call is logged with user ID, parameters, and success/failure status
## 🏗️ Architecture
### Authentication Flow
1. **Token Generation**: Discord token is embedded in JWT claims
2. **Request Authentication**: JWT is validated using RSA public key
3. **Token Extraction**: Discord token is extracted from validated JWT
4. **Tool Execution**: Temporary Discord bot connection is created
5. **Cleanup**: Bot connection is properly closed after operation
### Security Benefits
- **No token exposure**: Discord tokens never appear in request parameters
- **Centralized auth**: Single authentication point for all tools
- **Audit trail**: Complete logging of all authenticated operations
- **Temporary connections**: No persistent bot instances reduce attack surface
## 🔒 Security Considerations
### Development vs Production
- **Development**: Uses generated RSA key pairs (current setup)
- **Production**: Should use external OAuth 2.1 provider or IdP
### Token Security
- **JWT tokens expire** after 1 hour (configurable)
- **Discord tokens** are embedded in JWT claims, not visible in requests
- **RSA encryption** ensures token integrity
### Best Practices
1. **Rotate tokens regularly** in production
2. **Use HTTPS** for all communications
3. **Store Discord tokens securely** (environment variables, secrets manager)
4. **Monitor audit logs** for unusual activity
5. **Implement rate limiting** if needed
## 🤝 Integration with MCP Clients
This server follows the MCP specification and can be used with:
- **Claude Desktop** with MCP integration
- **Custom MCP clients**
- **API testing tools** (Postman, curl, etc.)
## 📚 References
- [FastMCP Documentation](https://gofastmcp.com)
- [FastMCP Bearer Token Auth](https://gofastmcp.com/servers/auth/bearer)
- [Discord.py Documentation](https://discordpy.readthedocs.io/)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
## 🐛 Troubleshooting
### Common Issues
1. **"No Discord token found in authentication"**
- Verify your JWT token contains the Discord token in claims
- Check token generation with correct Discord bot token
2. **"Bot doesn't have permission"**
- Ensure Discord bot has necessary permissions in the server
- Check channel permissions specifically
3. **"Server not reachable"**
- Verify server is running on localhost:8000
- Check for port conflicts
4. **"Invalid token"**
- Token may be expired (1 hour default)
- Generate a new token
- Verify token format in Authorization header