Provides comprehensive Slack workspace integration with tools for channel management (creating, archiving, listing channels), user management, messaging (sending, updating, deleting messages with Block Kit formatting), file uploads, emoji reactions, message search, and workspace information retrieval.
Slack MCP Server
A TypeScript-based Model Context Protocol (MCP) server that provides comprehensive Slack workspace integration. This server enables AI assistants to interact with Slack channels, users, messages, files, and more through the MCP protocol.
Table of Contents
Features
Channel Management
list_channels - List workspace channels with filtering options
get_channel_info - Get detailed information about a specific channel
create_channel - Create new public or private channels
archive_channel - Archive channels
User Management
list_users - List all users in the workspace
get_user_info - Get detailed user profile information
invite_to_channel - Invite users to channels
Messaging
send_message - Send text messages to channels
update_message - Update existing messages
delete_message - Delete messages
get_channel_history - Fetch message history with pagination
search_messages - Search messages across the workspace
send_formatted_message - Send messages with Block Kit formatting
File Operations
upload_file - Upload files to channels
Reactions
add_reaction - Add emoji reactions to messages
remove_reaction - Remove emoji reactions
Workspace Information
get_team_info - Get workspace/team information
Prerequisites
Before you begin, ensure you have:
Node.js 18 or higher - Verify with:
node --version
npm - Verify with:
npm --version
Slack workspace admin access - You need permission to create and install apps
Estimated setup time: ~20 minutes
Installation & Setup
Step 1: Project Setup (5 minutes)
Clone the repository and install dependencies:
ā Verification: Run npm list @modelcontextprotocol/sdk
to confirm the MCP SDK is installed.
Step 2: Create Slack App (10 minutes)
2.1 Create the App
Click "Create New App" ā "From scratch"
Enter an app name (e.g., "MCP Bot") and select your workspace
Click "Create App"
2.2 Configure OAuth Scopes
Navigate to "OAuth & Permissions" in the sidebar, scroll to "Scopes", and add these Bot Token Scopes:
Scope | Purpose | Used By |
| View basic channel information | list_channels, get_channel_info |
| Create channels | create_channel |
| Archive channels, invite users | archive_channel, invite_to_channel |
| View user profiles | list_users, get_user_info |
| Send and update messages | send_message, update_message, delete_message |
| Upload files to Slack | upload_file |
| Add/remove emoji reactions | add_reaction, remove_reaction |
| Get workspace information | get_team_info |
| Search messages | search_messages |
š” Tip: Each scope is necessary for specific tools to function. Missing scopes will cause "missing_scope" errors.
2.3 Install to Workspace
Scroll to "OAuth Tokens for Your Workspace"
Click "Install to Workspace"
Review permissions and click "Allow"
2.4 Copy Your Bot Token
After installation, you'll see the "Bot User OAuth Token"
Click "Copy" (token starts with
xoxb-
)Keep this token secure - you'll need it in the next step
ā Verification: Your token should look like: xoxb-<numbers>-<numbers>-<random-string>
Step 3: Configure Environment (2 minutes)
Create your environment configuration:
Edit .env
and add your bot token:
ā Verification: Run this command to confirm your token is loaded:
You should see: Token loaded: true
ā ļø Common Issue: Make sure your token starts with
xoxb-
(notxoxp-
orxoxa-
)
Step 4: Build & Verify (3 minutes)
Build the TypeScript project:
ā Verification: Confirm the build/
directory was created:
You should see the compiled index.js
file.
Testing Your Setup
Before integrating with Claude Desktop, test that everything works:
Using MCP Inspector
The MCP Inspector provides a GUI to test your tools:
This will open a web interface where you can:
See all available tools
Test individual tools with sample inputs
View responses and debug errors
Quick Test Commands
Try these simple tests in the MCP Inspector:
List channels:
Tool:
list_channels
Arguments:
{"limit": 5}
Expected: List of your workspace channels
Get team info:
Tool:
get_team_info
Arguments:
{}
Expected: Your workspace name and details
List users:
Tool:
list_users
Arguments:
{"limit": 5}
Expected: List of workspace users
ā Success Indicator: If these commands return data (not errors), your setup is working correctly!
ā ļø Troubleshooting: If you see "invalid_auth" or "token_revoked", double-check your
SLACK_BOT_TOKEN
in the.env
file.
Usage
With Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Option 1: Direct from GitHub (Recommended)
Use npx
to run directly from the GitHub repository:
Benefits:
ā No local installation needed
ā Always uses the latest version
ā Simpler configuration
ā Works on any machine with Node.js
Option 2: Local Installation
For local development or offline use:
Setup for local installation:
Clone and build the project (see Installation & Setup)
Replace
/absolute/path/to/slack-bot-mcp
with your full project pathFind it by running
pwd
in your project directoryExample:
/Users/yourname/projects/slack-bot-mcp/build/index.js
Important notes:
Token configuration: Set
SLACK_BOT_TOKEN
in the config file as shown aboveThe config file token takes precedence over
.env
filesKeep your token secure and never commit it to version control
Restart required: Restart Claude Desktop after editing the config file
First run: The first time using
npx
, it will download and cache the package (may take a few seconds)
ā Verification: Open Claude Desktop and type: "List my Slack channels". If configured correctly, Claude will use the list_channels
tool.
With Other MCP Clients
The server runs on stdio transport and can be integrated with any MCP client:
Development Mode
For development with hot reload:
Tool Examples
List Channels
Send Message
Send Formatted Message with Block Kit
Search Messages
Upload File
Add Reaction
Required OAuth Scopes
Make sure your Slack app has these scopes:
Scope | Purpose |
| List and get channel information |
| Create channels |
| Archive channels |
| List and get user information |
| Send, update, and delete messages |
| Upload files |
| Add and remove reactions |
| Get workspace information |
| Search messages |
Project Structure
Troubleshooting
Setup Issues
"SLACK_BOT_TOKEN environment variable is required"
Cause: The server can't find your bot token.
Solutions:
Verify
.env
file exists in project root:ls -la .env
Check token format:
cat .env
(should showSLACK_BOT_TOKEN=xoxb-...
)If using Claude Desktop config, ensure the token is in the
env
sectionRestart your MCP client after making changes
"Missing required OAuth scope"
Cause: Your bot token doesn't have necessary permissions.
Solution:
Go to https://api.slack.com/apps ā Your App ā "OAuth & Permissions"
Add the missing scope (error message will specify which one)
Click "Reinstall to Workspace" (this is required after adding scopes)
Copy the new bot token and update your configuration
š” Note: You must reinstall the app after changing scopes. The old token won't gain new permissions automatically.
Runtime Issues
"Channel not found" or "User not found"
Cause: You're using channel/user names instead of IDs.
Solution:
Channel IDs start with
C
(public),G
(private), orD
(DM)User IDs start with
U
Use
list_channels
orlist_users
tools to find the correct IDs
Example:
"invalid_auth" or "token_revoked"
Cause: Bot token is incorrect or expired.
Solution:
Go to https://api.slack.com/apps ā Your App ā "OAuth & Permissions"
Copy the current "Bot User OAuth Token"
Update your
.env
file or Claude Desktop configRestart the MCP server
Rate Limiting
Cause: Slack API has rate limits (Tier 3: 50+ requests per minute).
Solution:
Add delays between rapid requests
Use pagination parameters (limit, cursor) for large data sets
Monitor rate limit headers in error messages
MCP Inspector Won't Start
Cause: Port already in use or Node.js issues.
Solution:
Getting Help
If you're still stuck:
Check the build output: Run
npm run build
and look for TypeScript errorsVerify Node version: Run
node --version
(need 18+)Test token manually: Use Slack's API tester at https://api.slack.com/methods/auth.test/test
Enable debug logging: Set
DEBUG=*
environment variable
Still having issues? Open an issue at the GitHub repository with:
Error message (full text)
Your Node.js version
Steps to reproduce
Development
Building
Running in Development
Testing with MCP Inspector
License
ISC
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Acknowledgments
Ported from the Python implementation: https://github.com/piekstra/slack-mcp-server
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Enables comprehensive Slack workspace integration through AI assistants, allowing users to manage channels, send messages, upload files, search conversations, and interact with users through natural language commands.