README.md•14.1 kB
# 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](#features)
- [Prerequisites](#prerequisites)
- [Installation & Setup](#installation--setup)
- [Step 1: Project Setup](#step-1-project-setup-5-minutes)
- [Step 2: Create Slack App](#step-2-create-slack-app-10-minutes)
- [Step 3: Configure Environment](#step-3-configure-environment-2-minutes)
- [Step 4: Build & Verify](#step-4-build--verify-3-minutes)
- [Testing Your Setup](#testing-your-setup)
- [Usage](#usage)
- [Tool Examples](#tool-examples)
- [Troubleshooting](#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:
```bash
# 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
1. Go to https://api.slack.com/apps
2. Click **"Create New App"** → **"From scratch"**
3. Enter an app name (e.g., "MCP Bot") and select your workspace
4. 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
1. Scroll to **"OAuth Tokens for Your Workspace"**
2. Click **"Install to Workspace"**
3. Review permissions and click **"Allow"**
#### 2.4 Copy Your Bot Token
1. After installation, you'll see the **"Bot User OAuth Token"**
2. Click **"Copy"** (token starts with `xoxb-`)
3. 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:
```bash
# Copy the example file
cp .env.example .env
```
Edit `.env` and add your bot token:
```bash
SLACK_BOT_TOKEN=xoxb-your-actual-token-here
```
**✓ Verification:** Run this command to confirm your token is loaded:
```bash
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:
```bash
npm run build
```
**✓ Verification:** Confirm the `build/` directory was created:
```bash
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:
```bash
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:
1. **List channels:**
- Tool: `list_channels`
- Arguments: `{"limit": 5}`
- Expected: List of your workspace channels
2. **Get team info:**
- Tool: `get_team_info`
- Arguments: `{}`
- Expected: Your workspace name and details
3. **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:
```json
{
"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:
```json
{
"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:**
1. Clone and build the project (see [Installation & Setup](#installation--setup))
2. 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:**
1. **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
2. **Restart required:** Restart Claude Desktop after editing the config file
3. **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:
```bash
node build/index.js
```
### Development Mode
For development with hot reload:
```bash
npm run dev
```
## Tool Examples
### List Channels
```json
{
"name": "list_channels",
"arguments": {
"types": "public_channel,private_channel",
"exclude_archived": true,
"limit": 50
}
}
```
### Send Message
```json
{
"name": "send_message",
"arguments": {
"channel": "C1234567890",
"text": "Hello from MCP!"
}
}
```
### Send Formatted Message with Block Kit
```json
{
"name": "send_formatted_message",
"arguments": {
"channel": "C1234567890",
"text": "Fallback text",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Hello* from MCP with _formatting_!"
}
}
]
}
}
```
### Search Messages
```json
{
"name": "search_messages",
"arguments": {
"query": "important announcement",
"count": 10,
"sort": "timestamp"
}
}
```
### Upload File
```json
{
"name": "upload_file",
"arguments": {
"channels": ["C1234567890"],
"content": "File content here",
"filename": "report.txt",
"title": "Monthly Report"
}
}
```
### Add Reaction
```json
{
"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:**
1. Verify `.env` file exists in project root: `ls -la .env`
2. Check token format: `cat .env` (should show `SLACK_BOT_TOKEN=xoxb-...`)
3. If using Claude Desktop config, ensure the token is in the `env` section
4. Restart your MCP client after making changes
#### "Missing required OAuth scope"
**Cause:** Your bot token doesn't have necessary permissions.
**Solution:**
1. Go to https://api.slack.com/apps → Your App → "OAuth & Permissions"
2. Add the missing scope (error message will specify which one)
3. Click "Reinstall to Workspace" (this is required after adding scopes)
4. 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:**
```json
// ❌ Wrong
{"channel": "general"}
// ✓ Correct
{"channel": "C1234567890"}
```
#### "invalid_auth" or "token_revoked"
**Cause:** Bot token is incorrect or expired.
**Solution:**
1. Go to https://api.slack.com/apps → Your App → "OAuth & Permissions"
2. Copy the current "Bot User OAuth Token"
3. Update your `.env` file or Claude Desktop config
4. 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:**
```bash
# 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:
1. **Check the build output:** Run `npm run build` and look for TypeScript errors
2. **Verify Node version:** Run `node --version` (need 18+)
3. **Test token manually:** Use Slack's API tester at https://api.slack.com/methods/auth.test/test
4. **Enable debug logging:** Set `DEBUG=*` environment variable
Still having issues? Open an issue at the [GitHub repository](https://github.com/piekstra/slack-mcp-server) with:
- Error message (full text)
- Your Node.js version
- Steps to reproduce
## Development
### Building
```bash
npm run build
```
### Running in Development
```bash
npm run dev
```
### Testing with MCP Inspector
```bash
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