Slack MCP Server

# Slack MCP Server A Model Context Protocol (MCP) server that provides tools for interacting with Slack workspaces through the Slack Web API. ## Features ### Channel Management - **list_channels** - List all channels in the workspace - **get_channel_info** - Get detailed information about a specific channel - **create_channel** - Create a new channel - **archive_channel** - Archive a channel - **unarchive_channel** - Unarchive a channel - **set_channel_topic** - Set channel topic - **set_channel_purpose** - Set channel purpose ### User Management - **list_users** - List all users in the workspace - **get_user_info** - Get detailed information about a specific user - **invite_to_channel** - Invite users to a channel ### Messaging - **send_message** - Send a message to a channel (supports Block Kit) - **update_message** - Update an existing message (supports Block Kit) - **delete_message** - Delete a message - **get_channel_history** - Get message history for a channel - **search_messages** - Search for messages across the workspace ### Rich Message Formatting (Block Kit) - **send_formatted_message** - Send formatted messages with headers, sections, fields - **send_notification_message** - Send status notifications with emoji indicators - **send_list_message** - Send formatted lists with titles and descriptions ### File Management - **upload_file** - Upload a file to one or more channels ### Reactions - **add_reaction** - Add a reaction to a message - **remove_reaction** - Remove a reaction from a message ### Workspace - **get_team_info** - Get information about the Slack workspace/team ## Installation ### Using pip (Recommended - Global Install) For use with Claude Desktop or Claude CLI, install globally: ```bash pip install slack-mcp-server ``` ### From source ```bash git clone <repository-url> cd slack-mcp-server pip install -e . ``` ## Configuration ### Secure Credential Storage (Recommended) The Slack MCP Server uses macOS Keychain for secure credential storage. This is much safer than storing tokens in files. #### Quick Setup ```bash # Run the interactive setup slack-mcp-setup # or python -m slack_mcp.setup ``` The setup wizard will: 1. Guide you through obtaining a Slack API token 2. Securely store credentials in your macOS Keychain 3. Validate your configuration #### Manual Keychain Setup ```python from slack_mcp.credentials import CredentialManager manager = CredentialManager() manager.store_credential("api_token", "xoxb-your-slack-bot-token") manager.store_credential("workspace_id", "T1234567890") # Optional ``` ### Environment Variables (Fallback) If you prefer environment variables or are not on macOS, create a `.env` file: ```bash # Required SLACK_API_TOKEN=xoxb-your-slack-bot-token # Optional SLACK_WORKSPACE_ID=your-workspace-id ``` **⚠️ Security Warning**: Environment variables and `.env` files are less secure than keychain storage. ### Getting a Slack API Token 1. Go to [api.slack.com/apps](https://api.slack.com/apps) 2. Create a new app or select an existing one 3. Navigate to "OAuth & Permissions" 4. Add the required OAuth scopes (see below) 5. Install the app to your workspace 6. Copy the "Bot User OAuth Token" (starts with `xoxb-`) ### Required OAuth Scopes The following OAuth scopes are required for full functionality: **Core Scopes:** - `channels:read` - View basic channel information - `channels:manage` - Create and manage public channels - `groups:read` - View private channel information - `groups:write` - Create and manage private channels - `chat:write` - Send messages - `files:write` - Upload files - `im:read` - View direct message channels - `mpim:read` - View group direct message channels - `reactions:read` - View reactions - `reactions:write` - Add and remove reactions - `team:read` - View team information - `users:read` - View user information **⚠️ Search Limitation:** The `search_messages` tool uses Slack's search API which requires user tokens with the `search:read` scope. Since this server is designed for bot tokens (`xoxb-`), search functionality will not work. Consider removing this feature or switching to user token authentication if search is needed. ## Usage with Claude CLI (Recommended) After installing globally, add the server using Claude CLI. First, find your slack-mcp-server installation path: ```bash # Find your slack-mcp-server executable path which slack-mcp-server ``` Then add it with Claude CLI: ```bash claude mcp add slack /path/to/slack-mcp-server ``` For example: ```bash claude mcp add slack /usr/local/bin/slack-mcp-server ``` This automatically configures the server in your Claude Desktop configuration. ## Usage with Claude Desktop (Manual Configuration) Alternatively, you can manually add this to your `claude_desktop_config.json`: #### With Keychain Storage (Recommended) ```json { "mcpServers": { "slack": { "command": "python", "args": ["-m", "slack_mcp"] } } } ``` #### With Environment Variables ```json { "mcpServers": { "slack": { "command": "python", "args": ["-m", "slack_mcp"], "env": { "SLACK_API_TOKEN": "xoxb-your-slack-bot-token" } } } } ``` ## Usage with MCP Client ```python from mcp import Client # Initialize client client = Client() # Connect to the Slack MCP server await client.connect("python", ["-m", "slack_mcp"]) # List available tools tools = await client.list_tools() # Use a tool result = await client.call_tool("list_channels", { "types": "public_channel", "exclude_archived": True, "limit": 10 }) ``` ## Development ### Setting up the development environment ```bash # Clone the repository git clone <repository-url> cd slack-mcp-server # Create a virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install in development mode with dev dependencies pip install -e ".[dev]" # Set up credentials securely slack-mcp-setup ``` ### Running tests ```bash pytest ``` ### Code formatting ```bash # Format with black black slack_mcp/ # Lint with ruff ruff check slack_mcp/ ``` ## Examples ### List public channels ```python result = await client.call_tool("list_channels", { "types": "public_channel", "exclude_archived": True, "limit": 20 }) ``` ### Send a message ```python result = await client.call_tool("send_message", { "channel": "C1234567890", # Channel ID "text": "Hello from MCP!" }) ``` ### Search for messages ```python result = await client.call_tool("search_messages", { "query": "project deadline", "sort": "timestamp", "sort_dir": "desc", "count": 10 }) ``` ### Upload a file ```python result = await client.call_tool("upload_file", { "channels": "C1234567890,C0987654321", # Comma-separated channel IDs "content": "This is the file content", "filename": "report.txt", "title": "Weekly Report", "initial_comment": "Here's this week's report" }) ``` ### Send a formatted message with Block Kit ```python result = await client.call_tool("send_formatted_message", { "channel": "C1234567890", "title": "Project Update", "text": "Here's the latest update on our project progress", "fields": "Status: In Progress, Due Date: Next Friday, Assignee: @john", "context": "Last updated 2 hours ago" }) ``` ### Send a notification message ```python result = await client.call_tool("send_notification_message", { "channel": "C1234567890", "status": "success", "title": "Deployment Complete", "description": "The application has been successfully deployed to production", "details": "Build #123 deployed at 14:30 UTC" }) ``` ### Send a list message ```python result = await client.call_tool("send_list_message", { "channel": "C1234567890", "title": "Meeting Agenda", "description": "Items to discuss in today's standup", "items": "Sprint review\nBlocker discussion\nNext week planning\nDemo preparation" }) ``` ### Send message with custom Block Kit ```python result = await client.call_tool("send_message", { "channel": "C1234567890", "text": "Custom formatted message", "blocks": json.dumps([ { "type": "section", "text": { "type": "mrkdwn", "text": "*Important Notice*\nThis is a custom Block Kit message" } }, {"type": "divider"}, { "type": "context", "elements": [ { "type": "mrkdwn", "text": "Created with custom blocks" } ] } ]) }) ``` ## Error Handling The server returns JSON-formatted error messages when operations fail: ```json { "error": "Slack API error: channel_not_found" } ``` Common error codes: - `not_authed` - Invalid or missing API token - `channel_not_found` - Channel doesn't exist - `user_not_found` - User doesn't exist - `message_not_found` - Message doesn't exist - `no_permission` - Bot lacks required permissions - `rate_limited` - API rate limit exceeded ## Security Considerations - **🔐 Keychain Storage**: Use macOS Keychain for secure credential storage (recommended) - **API Token**: Never commit your Slack API token to version control - **Permissions**: Only grant the minimum required OAuth scopes - **Rate Limits**: The server respects Slack's rate limits (see [Slack Rate Limits](https://api.slack.com/docs/rate-limits)) - **Message Content**: Be mindful of sensitive information in messages and files ### Credential Management Commands ```bash # Interactive setup wizard slack-mcp-setup # View stored credentials python -c "from slack_mcp.credentials import CredentialManager; m = CredentialManager(); print(m.list_stored_credentials())" # Delete specific credential python -c "from slack_mcp.credentials import CredentialManager; CredentialManager().delete_credential('api_token')" ``` ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License MIT License - see LICENSE file for details ## Support For issues and questions, please create an issue in the repository.