{
  "markdown": "# Slack MCP Server\n\n<!-- mcp-name: io.github.stevenvo/slack-mcp-server -->\n\n[![PyPI](https://img.shields.io/pypi/v/slack-mcp-server-v2)](https://pypi.org/project/slack-mcp-server-v2/)\n[![Python Version](https://img.shields.io/pypi/pyversions/slack-mcp-server-v2)](https://pypi.org/project/slack-mcp-server-v2/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA Model Context Protocol (MCP) server that provides programmatic access to Slack conversations, threads, and workspace information. Designed for AI assistants like Claude to interact with your Slack workspace through a standardized interface.\n\n## What is MCP?\n\nThe [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that enables AI assistants to securely access external data sources and tools. This server implements MCP to give Claude direct access to your Slack workspace.\n\n## Features\n\n### 📨 Message Operations\n- **Read Channel Messages**: Fetch recent messages from any channel with flexible time-based filtering\n- **Read Thread Messages**: Access complete conversation threads including all replies\n- **Get Message Permalinks**: Generate permanent, shareable links to specific messages\n\n### 🔍 Discovery & Search\n- **List Your Channels**: Enumerate all channels you're a member of (public, private, DMs, group DMs)\n- **Search Conversations**: Find messages where you're mentioned or involved using Slack's search\n\n### 📊 Metadata & Context\n- **Get Channel Info**: View channel details, topics, purposes, member counts, and settings\n- **Get User Info**: Look up user profiles, emails, titles, timezones, and status information\n\n## Quick Start\n\n### Option 1: Install from PyPI (Recommended)\n\nThe easiest way to use this MCP server is to install it directly from PyPI:\n\n```bash\n# Install via pip\npip install slack-mcp-server-v2\n\n# Or install via uvx (recommended for MCP servers)\nuvx slack-mcp-server-v2\n```\n\n### Option 2: Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/stevenvo/slack-mcp-server.git\ncd slack-mcp-server\n\n# Install dependencies\npip install -r requirements.txt\n```\n\nAfter installation, you'll need to set up authentication (see below).\n\n## Authentication\n\n### Option 1: User Token (Recommended)\n\nA User Token uses your personal Slack permissions and can access all channels you're a member of.\n\n1. Go to https://api.slack.com/apps\n2. Create a new app (or use existing)\n3. Navigate to \"OAuth & Permissions\"\n4. Add the following **User Token Scopes**:\n   - `channels:history` - View messages in public channels\n   - `channels:read` - View basic channel info\n   - `groups:history` - View messages in private channels\n   - `groups:read` - View basic private channel info\n   - `im:history` - View messages in direct messages\n   - `im:read` - View basic DM info\n   - `mpim:history` - View messages in group DMs\n   - `mpim:read` - View basic group DM info\n   - `users:read` - View user information\n   - `search:read` - Search messages\n5. Install the app to your workspace\n6. Copy the \"User OAuth Token\" (starts with `xoxp-`)\n\n### Option 2: Bot Token\n\nA Bot Token is more limited but easier to set up for team-wide access.\n\n1. Follow steps 1-2 above\n2. Add **Bot Token Scopes** instead (same list but in bot section)\n3. Install the app\n4. Copy the \"Bot User OAuth Token\" (starts with `xoxb-`)\n5. Invite the bot to channels you want to read: `/invite @YourBotName`\n\n### Configure Environment\n\nCreate a `.env` file:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your token:\n\n```bash\n# Use one of these:\nSLACK_USER_TOKEN=xoxp-your-user-token-here\n# OR\nSLACK_BOT_TOKEN=xoxb-your-bot-token-here\n```\n\n## Configuration for Claude Code\n\nAdd this server to Claude Code by editing your `~/.claude.json` file:\n\n### Using PyPI Package (Recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"slack\": {\n      \"command\": \"uvx\",\n      \"args\": [\"slack-mcp-server-v2\"],\n      \"env\": {\n        \"SLACK_USER_TOKEN\": \"xoxp-your-user-token-here\",\n        \"SLACK_WORKSPACE_URL\": \"https://your-workspace.slack.com\"\n      }\n    }\n  }\n}\n```\n\n### Using Local Installation\n\nIf you installed from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"slack\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/slack-mcp-server/server.py\"],\n      \"env\": {\n        \"SLACK_USER_TOKEN\": \"xoxp-your-user-token-here\",\n        \"SLACK_WORKSPACE_URL\": \"https://your-workspace.slack.com\"\n      }\n    }\n  }\n}\n```\n\n### Using Bot Token\n\nIf you prefer to use a bot token instead of a user token:\n\n```json\n{\n  \"mcpServers\": {\n    \"slack\": {\n      \"command\": \"uvx\",\n      \"args\": [\"slack-mcp-server-v2\"],\n      \"env\": {\n        \"SLACK_BOT_TOKEN\": \"xoxb-your-bot-token-here\",\n        \"SLACK_WORKSPACE_URL\": \"https://your-workspace.slack.com\"\n      }\n    }\n  }\n}\n```\n\n**Note**: Remember to invite your bot to channels: `/invite @YourBotName`\n\n### Verify Installation\n\nRestart Claude Code and verify the server is running:\n\n```bash\nclaude mcp list\n```\n\nYou should see `slack` in the list of active MCP servers.\n\n## Available Tools\n\nThis server provides 7 MCP tools for interacting with Slack:\n\n### 📬 `read_channel_messages`\n\nRetrieve recent messages from any Slack channel with flexible time filtering.\n\n**Parameters:**\n| Name | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n| `channel_id` | string | ✅ | - | Slack channel ID (e.g., `C1234567890`) |\n| `lookback_hours` | number | ❌ | 24 | Hours to look back from now |\n| `limit` | number | ❌ | 100 | Max messages to retrieve (max: 1000) |\n\n**Natural Language Examples:**\n- \"Show me messages from the #general channel in the last 24 hours\"\n- \"Read the last 48 hours of messages from channel C1234567890\"\n- \"Get the most recent 50 messages from C070PDRHQS1\"\n\n**Returns:** Formatted messages with timestamps, user mentions, thread indicators, reactions, and permalinks.\n\n---\n\n### 💬 `read_thread_messages`\n\nRead all messages in a conversation thread, including the parent message and all replies.\n\n**Parameters:**\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| `channel_id` | string | ✅ | Channel ID where the thread exists |\n| `thread_ts` | string | ✅ | Thread timestamp (the `ts` field of the parent message) |\n\n**Natural Language Examples:**\n- \"Read the full thread with timestamp 1699564800.123456 in channel C1234567890\"\n- \"Show me all replies to message ts 1699564800.123456\"\n\n**Returns:** Complete thread with parent message and all replies, formatted with timestamps and reactions.\n\n---\n\n### 📋 `get_channel_info`\n\nGet detailed metadata about a Slack channel.\n\n**Parameters:**\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| `channel_id` | string | ✅ | Slack channel ID |\n\n**Natural Language Examples:**\n- \"Get info about channel C1234567890\"\n- \"Show me details for the #engineering channel\"\n\n**Returns:** Channel name, ID, creation date, member count, privacy status, topic, and purpose.\n\n---\n\n### 👤 `get_user_info`\n\nLook up detailed profile information for any Slack user.\n\n**Parameters:**\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| `user_id` | string | ✅ | Slack user ID (e.g., `U1234567`) |\n\n**Natural Language Examples:**\n- \"Get info about user U1234567\"\n- \"Show me details for @john.doe\"\n\n**Returns:** User's real name, display name, email, title, status, timezone, and admin/bot flags.\n\n---\n\n### 📑 `list_my_channels`\n\nList all channels you're a member of, with support for different channel types.\n\n**Parameters:**\n| Name | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n| `types` | string | ❌ | `public_channel,private_channel` | Comma-separated channel types |\n\n**Supported Types:**\n- `public_channel` - Public channels\n- `private_channel` - Private channels\n- `mpim` - Group direct messages\n- `im` - Direct messages\n\n**Natural Language Examples:**\n- \"List all my channels\"\n- \"Show me all private channels I'm in\"\n- \"List all my DMs\"\n\n**Returns:** Channel names, IDs, member counts, and privacy indicators.\n\n---\n\n### 🔍 `search_my_conversations`\n\nSearch for messages across all conversations where you're mentioned or involved.\n\n**Parameters:**\n| Name | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n| `query` | string | ✅ | - | Search terms |\n| `count` | number | ❌ | 20 | Number of results (max: 100) |\n\n**Natural Language Examples:**\n- \"Search my conversations for 'deployment'\"\n- \"Find messages mentioning 'bug fix' in the last week\"\n- \"Search for messages about 'Q4 planning'\"\n\n**Returns:** Matching messages with channel names, user info, timestamps, and permalinks.\n\n---\n\n### 🔗 `get_message_permalink`\n\nGenerate a permanent, shareable link to a specific Slack message.\n\n**Parameters:**\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| `channel_id` | string | ✅ | Channel ID |\n| `message_ts` | string | ✅ | Message timestamp |\n\n**Natural Language Examples:**\n- \"Get permalink for message 1699564800.123456 in channel C1234567890\"\n- \"Generate a link to this message\"\n\n**Returns:** Permanent URL that works even if the workspace's URL changes.\n\n## Usage Examples\n\nOnce configured in Claude Code, you can interact with your Slack workspace using natural language. Here are some example queries:\n\n### Reading Messages\n```\n👤 \"Show me the latest messages from #engineering\"\n🤖 [Claude fetches and displays recent messages with timestamps, users, and links]\n\n👤 \"What were the last 100 messages in the #product-updates channel from the past week?\"\n🤖 [Claude retrieves messages from the last 168 hours with limit of 100]\n```\n\n### Following Threads\n```\n👤 \"Read the full thread that starts at timestamp 1699564800.123456 in channel C1234567890\"\n🤖 [Claude displays the entire conversation thread with all replies]\n```\n\n### Discovery & Search\n```\n👤 \"List all channels I'm a member of\"\n🤖 [Claude shows all your public and private channels with member counts]\n\n👤 \"Search my Slack conversations for 'quarterly review'\"\n🤖 [Claude searches across all your messages and shows matches with context]\n\n👤 \"Find mentions of 'production deployment' in my conversations\"\n🤖 [Claude uses Slack search to find relevant messages]\n```\n\n### Getting Context\n```\n👤 \"Get info about channel C1234567890\"\n🤖 [Claude shows channel name, topic, member count, etc.]\n\n👤 \"Who is user U1234567?\"\n🤖 [Claude displays user profile with email, title, timezone]\n\n👤 \"Get me a permanent link to message 1699564800.123456 in #general\"\n🤖 [Claude generates a shareable permalink]\n```\n\n### Practical Workflows\n\n**Catch up on a project:**\n```\n👤 \"Show me all messages from #project-alpha in the last 3 days\"\n```\n\n**Find that important decision:**\n```\n👤 \"Search for messages about 'API migration decision'\"\n```\n\n**Get onboarding context:**\n```\n👤 \"List all channels I'm in and show me the purpose of each\"\n```\n\n## Finding Channel IDs\n\n### Method 1: From Slack URL\nWhen you're in a channel, the URL looks like:\n```\nhttps://your-workspace.slack.com/archives/C1234567890/p1234567890\n```\nThe part after `/archives/` is the channel ID: `C1234567890`\n\n### Method 2: Using the MCP Server\nAsk Claude:\n```\nList all my channels\n```\n\n### Method 3: Right-click in Slack\n1. Right-click on the channel name\n2. Click \"Copy link\"\n3. Extract the channel ID from the URL\n\n## Requirements\n\n- **Python**: 3.10 or higher\n- **Slack Workspace**: Admin access to create and configure a Slack app\n- **Claude Code**: Latest version with MCP support\n- **Operating System**: macOS, Linux, or Windows with WSL\n\n## Troubleshooting\n\n### \"Missing required scopes\" Error\n\nYour Slack app needs the proper OAuth scopes configured.\n\n**Solution:**\n1. Go to https://api.slack.com/apps and select your app\n2. Navigate to \"OAuth & Permissions\"\n3. Ensure you've added all required scopes listed in the Authentication section\n4. Reinstall the app to your workspace\n5. Copy the new token\n\n### \"Channel not found\" Error\n\n**For Bot Tokens:**\n```bash\n# Invite the bot to the channel first\n/invite @YourBotName\n```\n\n**For User Tokens:**\n- Verify you're a member of the channel\n- Check the channel ID is correct (see \"Finding Channel IDs\" section)\n\n### \"Not authenticated\" Error\n\n**Check your configuration:**\n```bash\n# Verify token is set correctly (check ~/.claude.json)\ncat ~/.claude.json | grep -A 5 \"slack\"\n\n# Ensure no extra whitespace\necho \"$SLACK_USER_TOKEN\" | wc -c\n```\n\n**Common issues:**\n- Token has expired or been revoked\n- Extra spaces or newlines in the token string\n- Wrong token type (user vs bot)\n- Token not properly quoted in JSON\n\n### MCP Server Not Running\n\n**Verify server is loaded:**\n```bash\n# List all MCP servers\nclaude mcp list\n\n# Check if slack server is running\nclaude mcp list | grep slack\n```\n\n**Check logs for errors:**\n```bash\n# View recent MCP server logs\ntail -f ~/.claude/debug/*.log\n\n# Filter for slack-related errors\ntail -f ~/.claude/debug/*.log | grep -i slack\n```\n\n**Common solutions:**\n1. Restart Claude Code completely\n2. Check `~/.claude.json` syntax is valid JSON\n3. Verify Python version: `python --version` (must be 3.10+)\n4. Test the server manually: `python server.py` (if installed from source)\n\n### SSL Certificate Errors\n\nIf you're behind a corporate proxy (like Zscaler):\n\n```bash\n# Set SSL certificate environment variable\nexport SSL_CERT_FILE=/path/to/your/ca-bundle.pem\nexport REQUESTS_CA_BUNDLE=/path/to/your/ca-bundle.pem\n\n# Then reinstall\npip install slack-mcp-server-v2\n```\n\n### Rate Limiting\n\nSlack API has rate limits. If you hit them:\n- Reduce the `limit` parameter in `read_channel_messages`\n- Increase `lookback_hours` to fetch fewer messages\n- Wait a few minutes before retrying\n\n**Rate limit indicators:**\n```\nError: ratelimited\n```\n\n**Solution:** The server will automatically handle rate limits, but you may need to wait.\n\n## Security & Privacy\n\n### Token Security\n\n- **Never commit tokens to version control** - The `.env` file is gitignored by default\n- **Revoke compromised tokens immediately** at https://api.slack.com/apps\n- **Use environment variables** in production, never hardcode tokens\n- **Rotate tokens periodically** as part of security best practices\n\n### Data Access\n\n**User Tokens:**\n- Have access to everything you can see in Slack\n- Use your personal permissions\n- See all channels you're a member of\n- More convenient for personal use\n\n**Bot Tokens:**\n- Limited to channels where the bot is invited\n- Separate from personal identity\n- Better for team/shared setups\n- More granular control\n\n### Corporate Environments\n\nIf you're using this in a corporate environment:\n- Check with your IT/Security team before creating Slack apps\n- Be aware of data retention and compliance policies\n- Consider using bot tokens for audit trails\n- SSL certificate configuration may be required (see Troubleshooting)\n\n## Limitations\n\n- **Read-only**: This server only reads data, it cannot post messages or modify content\n- **Rate limits**: Subject to Slack's API rate limits (Tier 3: ~50 requests per minute)\n- **Token scope**: Can only access channels/conversations the token has permission to see\n- **Message history**: Limited to Slack workspace's message retention policy\n\n## Contributing\n\nContributions are welcome! Here's how you can help:\n\n### Reporting Issues\n\nFound a bug or have a feature request?\n1. Check existing issues at https://github.com/stevenvo/slack-mcp-server/issues\n2. Create a new issue with:\n   - Clear description of the problem/feature\n   - Steps to reproduce (for bugs)\n   - Expected vs actual behavior\n   - Your environment (Python version, OS, Claude Code version)\n\n### Pull Requests\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Test thoroughly\n5. Commit with clear messages: `git commit -m \"Add amazing feature\"`\n6. Push to your fork: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n### Development Setup\n\n```bash\n# Clone your fork\ngit clone https://github.com/YOUR_USERNAME/slack-mcp-server.git\ncd slack-mcp-server\n\n# Install in development mode\npip install -e .\n\n# Make changes and test\npython server.py\n```\n\n## Changelog\n\n### v0.1.0 (2025-01-06)\n- Initial release\n- 7 core tools for reading Slack conversations\n- Support for user and bot tokens\n- Published to PyPI and MCP registry\n- Comprehensive documentation\n\n## Roadmap\n\nPotential future enhancements:\n- [ ] Support for Slack Enterprise Grid\n- [ ] Message filtering by user or reactions\n- [ ] Export conversations to different formats\n- [ ] Support for Slack Connect channels\n- [ ] Caching to reduce API calls\n- [ ] Webhook support for real-time updates\n\nSuggestions welcome in [GitHub Issues](https://github.com/stevenvo/slack-mcp-server/issues)!\n\n## Related Projects\n\n- [Model Context Protocol](https://modelcontextprotocol.io) - The MCP specification\n- [MCP Registry](https://registry.modelcontextprotocol.io) - Browse more MCP servers\n- [Slack SDK for Python](https://github.com/slackapi/python-slack-sdk) - The underlying library\n- [Claude Code](https://claude.com/claude-code) - AI assistant with MCP support\n\n## Support\n\n- **Documentation**: You're reading it!\n- **Issues**: https://github.com/stevenvo/slack-mcp-server/issues\n- **Discussions**: https://github.com/stevenvo/slack-mcp-server/discussions\n- **Slack API Docs**: https://api.slack.com/docs\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 Steven Vo\n\n---\n\n**Made with ❤️ for the MCP community**\n\nIf you find this useful, please ⭐ star the repository on GitHub!\n",
  "bytes": 17627,
  "sha": "73fc209cbb8632dad4f55bc26272c5eb0d94c18817b2b65cd7f8b1c7d171c6f6",
  "repo_slug": "stevenvo/slack-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_stevenvo_slack_mcp_server_0d2a2dec/readme"
}