slack-mpm

slack-mpm

A Python MCP (Model Context Protocol) server and API library for Slack workspace integration. Exposes 40+ Slack operations as MCP tools for use with Claude Desktop, and provides a clean async Python API for building Slack integrations.

What It Is

• Python API library: from slack_mpm.api import messages; await messages.send_message(...)
• MCP server: wraps the API for Claude Desktop via slack-mpm mcp
• Agent scripts: standalone automation scripts in agents/

Prerequisites

1. Python 3.10+ and uv
2. A Slack App with a bot token

Creating a Slack App

1. Go to https://api.slack.com/apps and click "Create New App"
2. Choose "From scratch", give it a name and select your workspace
3. Go to "OAuth & Permissions" and add these Bot Token Scopes:
   • channels:read, channels:write, channels:manage
   • chat:write, chat:write.public
   • users:read
   • files:read, files:write
   • reactions:write
   • pins:write
   • bookmarks:read, bookmarks:write
   • emoji:read
   • groups:read, groups:write
   • im:read, im:write
   • mpim:read, mpim:write
4. Install the app to your workspace
5. Copy the "Bot User OAuth Token" (starts with xoxb-)

For search_messages and reminders, also create a User Token with search:read, reminders:read, reminders:write.

Quick Start

git clone <repo>
cd slack-mpm
cp .env.local.example .env.local
# Edit .env.local and add your SLACK_BOT_TOKEN=xoxb-...

uv sync
uv run slack-mpm setup   # Verify your token works
uv run slack-mpm doctor  # Health check

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "slack": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/slack-mpm", "slack-mpm", "mcp"]
    }
  }
}

Restart Claude Desktop. You should see the Slack tools available.

Available Tools

Channel Tools (8)

Message Tools (13)

User Tools (5)

File Tools (5)

Workspace Tools (4)

Reminder Tools (4)

Bookmark Tools (3)

Scheduled Message Tools (3)

Using the Python API Directly

import asyncio
from slack_mpm.api import messages, channels, users
from slack_mpm.auth.token_manager import TokenManager

async def main():
    token = TokenManager().get_token()

    # Send a message
    await messages.send_message(token, "#general", "Hello from Python!")

    # List channels
    data = await channels.list_channels(token)
    for ch in data["channels"]:
        print(ch["name"])

    # Get user info
    user = await users.get_user_by_email(token, "[email protected]")
    print(user["user"]["real_name"])

asyncio.run(main())

Agent Scripts

Standalone automation scripts in the agents/ directory.

slack_listener.py — Real-time channel monitor

Polls a channel and prints new messages as they arrive.

uv run agents/slack_listener.py --channel C1234567890
uv run agents/slack_listener.py --channel C1234567890 --interval 10
uv run agents/slack_listener.py --channel C1234567890 --no-history

slack_notifier.py — Send notifications

Sends messages or file uploads to Slack channels from the command line or stdin.

uv run agents/slack_notifier.py --channel C1234567890 --message "Deploy complete"
echo "alert!" | uv run agents/slack_notifier.py --channel C1234567890
cat report.txt | uv run agents/slack_notifier.py --channel C1234567890 --as-file --filename report.txt

slack_responder.py — Auto-responder bot

Monitors for @mentions or DMs and auto-replies with a configured message.

uv run agents/slack_responder.py --response "Thanks, I'll get back to you!"
uv run agents/slack_responder.py --channel C1234567890 --response "Got it!" --interval 60
uv run agents/slack_responder.py --response "Out of office" --dry-run

slack_digest.py — Activity digest

Generates a summary of recent channel activity: message counts, active users, top threads.

uv run agents/slack_digest.py --channel C1234567890
uv run agents/slack_digest.py --channel C1234567890 --hours 168  # 1 week
uv run agents/slack_digest.py --channel C1234567890 --hours 24 --top-users 10

slack_archiver.py — Channel history export

Exports complete channel message history to JSON or Markdown files with thread support.

uv run agents/slack_archiver.py --channel C1234567890 --output ./archive/
uv run agents/slack_archiver.py --channel C1234567890 --output ./archive/ --format markdown
uv run agents/slack_archiver.py --channel C1234567890 --output ./archive/ --days 30

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest
uv run pytest --cov=src --cov-report=html

# Type checking
uv run mypy --strict src/

# Linting
uv run ruff check src/ agents/
uv run ruff format src/ agents/

Project Structure

src/slack_mpm/
├── api/
│   ├── _client.py      # Shared httpx client + SlackAPIError
│   ├── channels.py     # Channel operations
│   ├── messages.py     # Message operations
│   ├── users.py        # User operations
│   ├── files.py        # File operations
│   ├── workspace.py    # Workspace operations
│   ├── reminders.py    # Reminder operations
│   ├── bookmarks.py    # Bookmark operations
│   └── scheduled.py    # Scheduled message operations
├── auth/
│   ├── models.py       # SlackToken, TokenStatus, WorkspaceInfo
│   └── token_manager.py # TokenManager (loads from .env.local)
├── cli/
│   └── main.py         # CLI: setup, doctor, mcp commands
└── server/
    └── slack_mpm_server.py  # SlackMCPServer (MCP adapter)

agents/
├── slack_listener.py   # Channel message poller
├── slack_notifier.py   # Send notifications
├── slack_responder.py  # Auto-responder bot
├── slack_digest.py     # Activity digest
└── slack_archiver.py   # History export