stoat-mcp

Stoat MCP Server

   

A Model Context Protocol (MCP) server for the Stoat chat platform. Gives AI assistants structured access to Stoat servers, channels, messages, and users.

Built with FastMCP and stoat.py.

Installation

pip install stoat-mcp

Or run from source:

git clone https://github.com/mdlopresti/stoat-mcp.git
cd stoat-mcp
pip install -e ".[dev]"

Quick Start

Set required environment variables:

export STOAT_TOKEN="your-bot-token"
export STOAT_SERVER_ID="your-server-id"

Run the server:

stoat-mcp

Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | STOAT_TOKEN | Yes | — | Bot authentication token | | STOAT_SERVER_ID | Yes | — | Stoat server ID to operate on | | STOAT_ENABLE_WRITE | No | false | Master switch for all write operations | | STOAT_ENABLE_SEND_MESSAGE | No | false | Enable send_message tool | | STOAT_ENABLE_SEND_DM | No | false | Enable send_direct_message tool | | STOAT_CHANNEL_ALLOWLIST | No | "" | Comma-separated channel IDs (empty = all allowed) | | STOAT_CHANNEL_BLOCKLIST | No | "" | Comma-separated channel IDs (empty = none blocked) |

Write Operations

All write operations (sending messages, creating channels, etc.) are disabled by default. To enable them:

# Enable all write operations
export STOAT_ENABLE_WRITE=true

# Or enable specific operations
export STOAT_ENABLE_SEND_MESSAGE=true
export STOAT_ENABLE_SEND_DM=true

Channel Filtering

Restrict which channels the MCP server can access:

# Only allow these channels (empty = all channels)
export STOAT_CHANNEL_ALLOWLIST="channel-id-1,channel-id-2"

# Block these channels (applied before allowlist)
export STOAT_CHANNEL_BLOCKLIST="private-channel-id"

The blocklist takes precedence: a channel in both lists is blocked.

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stoat": {
      "command": "stoat-mcp",
      "env": {
        "STOAT_TOKEN": "your-bot-token",
        "STOAT_SERVER_ID": "your-server-id"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "stoat": {
      "command": "stoat-mcp",
      "env": {
        "STOAT_TOKEN": "your-bot-token",
        "STOAT_SERVER_ID": "your-server-id"
      }
    }
  }
}

Available Tools

| Category | Tool | Tier | Description | |----------|------|------|-------------| | Channels | list_channels | Read | List all accessible text channels | | Channels | get_channel_info | Read | Get metadata for a specific channel | | Channels | create_channel | Write | Create a new text channel | | Channels | delete_channel | Write | Delete a text channel | | Messages | get_channel_messages | Read | Read message history from a channel | | Messages | send_message | Write | Send a message to a channel | | Users | list_users | Read | List server members | | Users | get_user_info | Read | Get profile data for a specific user | | DMs | get_direct_messages | Read | Read DM history with a user | | DMs | send_direct_message | Write | Send a direct message to a user | | Search | search_messages | Read | Search messages across channels | | Threads | get_thread_replies | Read | Get replies in a message thread | | Threads | reply_to_thread | Write | Reply to a message thread | | Reactions | add_reaction | Write | Add an emoji reaction to a message | | Reactions | remove_reaction | Write | Remove an emoji reaction from a message | | Files | upload_file | Write | Upload a file to a channel |

Comparable Projects

• Discord MCP — MCP server for Discord
• Slack MCP — Official MCP server for Slack

stoat-mcp is the first MCP server for the Stoat (formerly Revolt) platform.

Security

The Lethal Trifecta

This MCP server creates a combination that requires careful consideration:

1. AI with access to private messages — the AI can read chat history
2. AI with ability to send messages — the AI can communicate externally
3. User-controlled message content — messages may contain prompt injection attempts

This combination means a malicious message in a channel could potentially instruct the AI to exfiltrate private data from other channels by sending it somewhere attacker-controlled.

Mitigations

• Write operations are disabled by default. Only enable STOAT_ENABLE_WRITE or STOAT_ENABLE_SEND_MESSAGE when you specifically need the AI to send messages.
• Use the channel blocklist to prevent the AI from reading sensitive channels: STOAT_CHANNEL_BLOCKLIST="private-channel,admin-channel"
• Use the channel allowlist to restrict the AI to only specific channels: STOAT_CHANNEL_ALLOWLIST="ai-channel,support-channel"
• Review AI actions before approving message sends in your MCP client.

Recommendations

• Start with read-only access and only enable writes when needed
• Use the most restrictive channel filtering that meets your needs
• Never put secrets or credentials in channels the AI can read
• Monitor AI-sent messages for unexpected behavior

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific test file
pytest tests/test_config.py

License

MIT