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)

Tool	Description
list_channels	List all channels (public + private)
get_channel_info	Get details about a channel
create_channel	Create a new channel
archive_channel	Archive a channel
invite_to_channel	Invite users to a channel
kick_from_channel	Remove a user from a channel
join_channel	Join a channel
set_channel_topic	Set channel topic

Message Tools (13)

Tool	Description
send_message	Send a message (supports blocks + threading)
send_ephemeral	Send a message visible only to one user
update_message	Edit an existing message
delete_message	Delete a message
get_permalink	Get a permanent link to a message
search_messages	Search messages (requires user token)
list_history	Fetch channel message history
add_reaction	Add emoji reaction
remove_reaction	Remove emoji reaction
pin_message	Pin a message
unpin_message	Unpin a message
reply_in_thread	Reply in a thread
get_thread_replies	Fetch all thread replies

User Tools (5)

Tool	Description
list_users	List all workspace users
get_user_info	Get user details
get_user_by_email	Look up a user by email
open_dm	Open a DM channel with user(s)
list_user_channels	List channels a user belongs to

File Tools (5)

Tool	Description
upload_file	Upload a file to channel(s)
list_files	List workspace files
get_file_info	Get file details
delete_file	Delete a file
share_file	Share an existing file to channels

Workspace Tools (4)

Tool	Description
get_workspace_info	Get workspace/team info
list_emojis	List custom emoji
get_bot_info	Get bot details
auth_test	Validate token

Reminder Tools (4)

Tool	Description
add_reminder	Create a reminder
list_reminders	List reminders
complete_reminder	Mark reminder complete
delete_reminder	Delete a reminder

Bookmark Tools (3)

Tool	Description
list_bookmarks	List channel bookmarks
add_bookmark	Add a bookmark to a channel
remove_bookmark	Remove a bookmark

Scheduled Message Tools (3)

Tool	Description
schedule_message	Schedule a future message
list_scheduled_messages	List pending scheduled messages
delete_scheduled_message	Cancel a scheduled message

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, "person@example.com")
    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