A standalone MCP (Model Context Protocol) server for Mattermost integration, built with FastMCP 3.0.

• Message Operations: Send, get, edit, delete messages
• File Operations: Upload and download files
• Channel Management: List and get channel information
• Real-time Subscriptions: WebSocket-based message stream
• Blocking Wait: wait_for_message for reactive bot behavior
• FastMCP 3.0: Modern decorator-based tool registration

# From source
cd /workspace/botmcp
pip install -e .

# Or using pip (after publishing)
pip install botmcp

Set environment variables:

export MATTERMOST_URL="http://zjty.net:6065"
export MATTERMOST_TOKEN="5z3rk5fwftbo3gmdhbzskyauah"

Or create a .env file:

MATTERMOST_URL=http://zjty.net:6065
MATTERMOST_TOKEN=5z3rk5fwftbo3gmdhbzskyauah

注：以上为测试环境账户（garry bot）

Step 1: Start BotMCP SSE server

cd /workspace/botmcp

export MATTERMOST_URL="http://zjty.net:6065"
export MATTERMOST_TOKEN="5z3rk5fwftbo3gmdhbzskyauah"

# SSE transport (recommended)
fastmcp run run_server.py --transport sse --port 8000

Step 2: Configure ~/.codebuddy/mcp.json

{
  "mcpServers": {
    "botmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "transport": "sse"
    }
  }
}

Add to ~/.codebuddy/mcp.json:

{
  "mcpServers": {
    "botmcp": {
      "command": "python",
      "args": ["-m", "botmcp.server"],
      "env": {
        "MATTERMOST_URL": "http://zjty.net:6065",
        "MATTERMOST_TOKEN": "5z3rk5fwftbo3gmdhbzskyauah"
      }
    }
  }
}

Add to your Claude Desktop config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mattermost": {
      "command": "python",
      "args": ["-m", "botmcp.server"],
      "env": {
        "MATTERMOST_URL": "http://zjty.net:6065",
        "MATTERMOST_TOKEN": "5z3rk5fwftbo3gmdhbzskyauah"
      }
    }
  }
}

# Start the MCP server (stdio transport)
python -m botmcp.server

# Or using FastMCP CLI
fastmcp run botmcp.server:mcp

# With HTTP transport
fastmcp run botmcp.server:mcp --transport http --port 8000

Tool	Description
send_message	Send a message to a channel
get_message	Get a message by ID
edit_message	Edit an existing message
delete_message	Delete a message
get_thread	Get all posts in a thread
get_channel_messages	Get recent messages from a channel
search_messages	Search for messages

Tool	Description
upload_file	Upload a file to a channel
download_file	Download a file
get_file_info	Get file metadata

Tool	Description
get_channel	Get channel information
list_channels	List channels in a team
get_my_channels	Get channels for current user

Tool	Description
wait_for_message	Block until new message arrives (for reactive bots)
get_realtime_messages	Get current message queue
subscribe_channel	Subscribe to channel events
mark_message_completed	Mark message as processed

URI	Description
mattermost://messages/stream	Real-time message stream
mattermost://bot/status	Bot connection status
mattermost://channels/subscribed	List of monitored channels

{
  "name": "send_message",
  "arguments": {
    "channel_id": "abc123",
    "message": "Hello from BotMCP!"
  }
}

{
  "name": "send_message",
  "arguments": {
    "channel_id": "abc123",
    "message": "This is a reply",
    "root_id": "parent_post_id"
  }
}

{
  "name": "upload_file",
  "arguments": {
    "channel_id": "abc123",
    "file_name": "document.pdf",
    "file_data": "<base64-encoded-data>",
    "content_type": "application/pdf"
  }
}

Variable	Required	Default	Description
MATTERMOST_URL	Yes	-	Mattermost server URL
MATTERMOST_TOKEN	Yes	-	Bot token or personal access token
MATTERMOST_TEAM	No	-	Default team name
WEBSOCKET_ENABLED	No	true	Enable WebSocket
WEBSOCKET_RECONNECT_DELAY	No	5	Reconnection delay (seconds)
WEBSOCKET_MAX_RETRIES	No	10	Maximum reconnection attempts
MESSAGE_QUEUE_SIZE	No	100	Message queue size
MAX_FILE_SIZE	No	52428800	Max upload size (50MB)

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

# Run tests
pytest

# Type checking
mypy src/botmcp

# Linting
ruff check src/botmcp

Built with FastMCP 3.0 - a modern, decorator-based MCP framework:

from fastmcp import FastMCP

mcp = FastMCP("BotMCP")

@mcp.tool
async def send_message(channel_id: str, message: str) -> str:
    """Send a message to a Mattermost channel."""
    ...

@mcp.resource("mattermost://messages/stream")
async def get_messages_resource() -> str:
    """Real-time message stream resource."""
    ...

MIT License