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.

Features
Prerequisites
Installation & Setup
Testing Your Setup
Usage
Tool Examples
Troubleshooting

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:

# Clone the repository
git clone <your-repo-url>
cd slack-bot-mcp

# Install dependencies
npm install

✓ 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

Go to https://api.slack.com/apps
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
`channels:read`	View basic channel information	list_channels, get_channel_info
`channels:write`	Create channels	create_channel
`channels:manage`	Archive channels, invite users	archive_channel, invite_to_channel
`users:read`	View user profiles	list_users, get_user_info
`chat:write`	Send and update messages	send_message, update_message, delete_message
`files:write`	Upload files to Slack	upload_file
`reactions:write`	Add/remove emoji reactions	add_reaction, remove_reaction
`team:read`	Get workspace information	get_team_info
`search:read`	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:

# Copy the example file
cp .env.example .env

Edit .env and add your bot token:

SLACK_BOT_TOKEN=xoxb-your-actual-token-here

✓ Verification: Run this command to confirm your token is loaded:

node -e "require('dotenv').config(); console.log('Token loaded:', !!process.env.SLACK_BOT_TOKEN)"

You should see: Token loaded: true

⚠️ Common Issue: Make sure your token starts with xoxb- (not xoxp- or xoxa-)

Step 4: Build & Verify (3 minutes)

Build the TypeScript project:

npm run build

✓ Verification: Confirm the build/ directory was created:

ls build/index.js

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:

npx @modelcontextprotocol/inspector node build/index.js

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:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "github:Hais/slack-bot-mcp"
      ],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

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:

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["/absolute/path/to/slack-bot-mcp/build/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

Setup for local installation:

Clone and build the project (see Installation & Setup)
Replace /absolute/path/to/slack-bot-mcp with your full project path
- Find it by running pwd in your project directory
- Example: /Users/yourname/projects/slack-bot-mcp/build/index.js

Important notes:

Token configuration: Set SLACK_BOT_TOKEN in the config file as shown above
- The config file token takes precedence over .env files
- Keep 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:

node build/index.js

Development Mode

For development with hot reload:

npm run dev

Tool Examples

List Channels

{
  "name": "list_channels",
  "arguments": {
    "types": "public_channel,private_channel",
    "exclude_archived": true,
    "limit": 50
  }
}

Send Message

{
  "name": "send_message",
  "arguments": {
    "channel": "C1234567890",
    "text": "Hello from MCP!"
  }
}

Send Formatted Message with Block Kit

{
  "name": "send_formatted_message",
  "arguments": {
    "channel": "C1234567890",
    "text": "Fallback text",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "*Hello* from MCP with _formatting_!"
        }
      }
    ]
  }
}

Search Messages

{
  "name": "search_messages",
  "arguments": {
    "query": "important announcement",
    "count": 10,
    "sort": "timestamp"
  }
}

Upload File

{
  "name": "upload_file",
  "arguments": {
    "channels": ["C1234567890"],
    "content": "File content here",
    "filename": "report.txt",
    "title": "Monthly Report"
  }
}

Add Reaction

{
  "name": "add_reaction",
  "arguments": {
    "channel": "C1234567890",
    "timestamp": "1234567890.123456",
    "name": "thumbsup"
  }
}

Required OAuth Scopes

Make sure your Slack app has these scopes:

Scope	Purpose
`channels:read`	List and get channel information
`channels:write`	Create channels
`channels:manage`	Archive channels
`users:read`	List and get user information
`chat:write`	Send, update, and delete messages
`files:write`	Upload files
`reactions:write`	Add and remove reactions
`team:read`	Get workspace information
`search:read`	Search messages

Project Structure

slack-bot-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── channels.ts       # Channel management tools
│   │   ├── users.ts          # User management tools
│   │   ├── messages.ts       # Messaging tools
│   │   ├── files.ts          # File upload tool
│   │   ├── reactions.ts      # Reaction tools
│   │   └── workspace.ts      # Workspace info tool
│   ├── config/
│   │   └── credentials.ts    # Environment config loader
│   ├── types/
│   │   └── slack.ts          # TypeScript interfaces
│   └── utils/
│       ├── slack-client.ts   # Slack API wrapper
│       └── validators.ts     # Zod input validators
├── build/                    # Compiled JavaScript
├── .env                      # Your environment variables
├── .env.example             # Environment template
├── package.json
├── tsconfig.json
└── README.md

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 show SLACK_BOT_TOKEN=xoxb-...)
If using Claude Desktop config, ensure the token is in the env section
Restart 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), or D (DM)
User IDs start with U
Use list_channels or list_users tools to find the correct IDs

Example:

// ❌ Wrong
{"channel": "general"}

// ✓ Correct
{"channel": "C1234567890"}

"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 config
Restart 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:

# Kill any existing inspector processes
pkill -f "mcp.*inspector"

# Try again
npx @modelcontextprotocol/inspector node build/index.js

Getting Help

If you're still stuck:

Check the build output: Run npm run build and look for TypeScript errors
Verify 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

npm run build

Running in Development

npm run dev

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

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

Slack MCP Server

Features
Prerequisites
Installation & Setup
Testing Your Setup
Usage
Tool Examples
Troubleshooting

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:

# Clone the repository
git clone <your-repo-url>
cd slack-bot-mcp

# Install dependencies
npm install

✓ 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

Go to https://api.slack.com/apps
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
`channels:read`	View basic channel information	list_channels, get_channel_info
`channels:write`	Create channels	create_channel
`channels:manage`	Archive channels, invite users	archive_channel, invite_to_channel
`users:read`	View user profiles	list_users, get_user_info
`chat:write`	Send and update messages	send_message, update_message, delete_message
`files:write`	Upload files to Slack	upload_file
`reactions:write`	Add/remove emoji reactions	add_reaction, remove_reaction
`team:read`	Get workspace information	get_team_info
`search:read`	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:

# Copy the example file
cp .env.example .env

Edit .env and add your bot token:

SLACK_BOT_TOKEN=xoxb-your-actual-token-here

✓ Verification: Run this command to confirm your token is loaded:

node -e "require('dotenv').config(); console.log('Token loaded:', !!process.env.SLACK_BOT_TOKEN)"

You should see: Token loaded: true

⚠️ Common Issue: Make sure your token starts with xoxb- (not xoxp- or xoxa-)

Step 4: Build & Verify (3 minutes)

Build the TypeScript project:

npm run build

✓ Verification: Confirm the build/ directory was created:

ls build/index.js

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:

npx @modelcontextprotocol/inspector node build/index.js

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:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "github:Hais/slack-bot-mcp"
      ],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

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:

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["/absolute/path/to/slack-bot-mcp/build/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

Setup for local installation:

Clone and build the project (see Installation & Setup)
Replace /absolute/path/to/slack-bot-mcp with your full project path
- Find it by running pwd in your project directory
- Example: /Users/yourname/projects/slack-bot-mcp/build/index.js

Important notes:

Token configuration: Set SLACK_BOT_TOKEN in the config file as shown above
- The config file token takes precedence over .env files
- Keep 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:

node build/index.js

Development Mode

For development with hot reload:

npm run dev

Tool Examples

List Channels

{
  "name": "list_channels",
  "arguments": {
    "types": "public_channel,private_channel",
    "exclude_archived": true,
    "limit": 50
  }
}

Send Message

{
  "name": "send_message",
  "arguments": {
    "channel": "C1234567890",
    "text": "Hello from MCP!"
  }
}

Send Formatted Message with Block Kit

{
  "name": "send_formatted_message",
  "arguments": {
    "channel": "C1234567890",
    "text": "Fallback text",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "*Hello* from MCP with _formatting_!"
        }
      }
    ]
  }
}

Search Messages

{
  "name": "search_messages",
  "arguments": {
    "query": "important announcement",
    "count": 10,
    "sort": "timestamp"
  }
}

Upload File

{
  "name": "upload_file",
  "arguments": {
    "channels": ["C1234567890"],
    "content": "File content here",
    "filename": "report.txt",
    "title": "Monthly Report"
  }
}

Add Reaction

{
  "name": "add_reaction",
  "arguments": {
    "channel": "C1234567890",
    "timestamp": "1234567890.123456",
    "name": "thumbsup"
  }
}

Required OAuth Scopes

Make sure your Slack app has these scopes:

Scope	Purpose
`channels:read`	List and get channel information
`channels:write`	Create channels
`channels:manage`	Archive channels
`users:read`	List and get user information
`chat:write`	Send, update, and delete messages
`files:write`	Upload files
`reactions:write`	Add and remove reactions
`team:read`	Get workspace information
`search:read`	Search messages

Project Structure

slack-bot-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── channels.ts       # Channel management tools
│   │   ├── users.ts          # User management tools
│   │   ├── messages.ts       # Messaging tools
│   │   ├── files.ts          # File upload tool
│   │   ├── reactions.ts      # Reaction tools
│   │   └── workspace.ts      # Workspace info tool
│   ├── config/
│   │   └── credentials.ts    # Environment config loader
│   ├── types/
│   │   └── slack.ts          # TypeScript interfaces
│   └── utils/
│       ├── slack-client.ts   # Slack API wrapper
│       └── validators.ts     # Zod input validators
├── build/                    # Compiled JavaScript
├── .env                      # Your environment variables
├── .env.example             # Environment template
├── package.json
├── tsconfig.json
└── README.md

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 show SLACK_BOT_TOKEN=xoxb-...)
If using Claude Desktop config, ensure the token is in the env section
Restart 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), or D (DM)
User IDs start with U
Use list_channels or list_users tools to find the correct IDs

Example:

// ❌ Wrong
{"channel": "general"}

// ✓ Correct
{"channel": "C1234567890"}

"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 config
Restart 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:

# Kill any existing inspector processes
pkill -f "mcp.*inspector"

# Try again
npx @modelcontextprotocol/inspector node build/index.js

Getting Help

If you're still stuck:

Check the build output: Run npm run build and look for TypeScript errors
Verify 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

npm run build

Running in Development

npm run dev

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

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

Slack MCP Server

Slack MCP Server

Table of Contents

Features

Channel Management

User Management

Messaging

File Operations

Reactions

Workspace Information

Prerequisites

Installation & Setup

Step 1: Project Setup (5 minutes)

Step 2: Create Slack App (10 minutes)

2.1 Create the App

2.2 Configure OAuth Scopes

2.3 Install to Workspace

2.4 Copy Your Bot Token

Step 3: Configure Environment (2 minutes)

Step 4: Build & Verify (3 minutes)

Testing Your Setup

Using MCP Inspector

Quick Test Commands

Usage

With Claude Desktop

Option 1: Direct from GitHub (Recommended)

Option 2: Local Installation

With Other MCP Clients

Development Mode

Tool Examples

List Channels

Send Message

Send Formatted Message with Block Kit

Search Messages

Upload File

Add Reaction

Required OAuth Scopes

Project Structure

Troubleshooting

Setup Issues

"SLACK_BOT_TOKEN environment variable is required"

"Missing required OAuth scope"

Runtime Issues

"Channel not found" or "User not found"

"invalid_auth" or "token_revoked"

Rate Limiting

MCP Inspector Won't Start

Getting Help

Development

Building

Running in Development

Testing with MCP Inspector

License

Contributing

Acknowledgments

Slack MCP Server

Table of Contents

Features

Channel Management

User Management

Messaging

File Operations

Reactions

Workspace Information

Prerequisites

Installation & Setup

Step 1: Project Setup (5 minutes)

Step 2: Create Slack App (10 minutes)

2.1 Create the App

2.2 Configure OAuth Scopes

2.3 Install to Workspace

2.4 Copy Your Bot Token

Step 3: Configure Environment (2 minutes)

Step 4: Build & Verify (3 minutes)

Testing Your Setup

Using MCP Inspector

Quick Test Commands

Usage

With Claude Desktop

Option 1: Direct from GitHub (Recommended)