# Slack MCP Server
A Model Context Protocol (MCP) server for Slack API integration. This server allows AI assistants to interact with Slack workspaces through OAuth 2.0 authenticated user tokens.
## Features
- **Channel Operations**: List channels, get channel info, get channel members
- **Message Operations**: Read messages, send messages, reply to threads, search messages
- **User Operations**: List users, get user info, get user profiles
- **File Operations**: List files, get file info, upload files
- **Reaction Operations**: Add/remove reactions, get message reactions
## Prerequisites
- Node.js 18+
- A Slack App with OAuth 2.0 configured
- User token (xoxp-...) with appropriate scopes
## Installation
```bash
npm install
npm run build
```
## Slack App Setup
### 1. Create a Slack App
1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click "Create New App" → "From scratch"
3. Enter app name and select workspace
### 2. Configure OAuth Scopes
Add these **User Token Scopes** under "OAuth & Permissions":
```
channels:read # List channels
channels:history # Read channel messages
groups:read # List private channels
groups:history # Read private channel messages
im:read # List direct messages
im:history # Read direct messages
mpim:read # List group DMs
mpim:history # Read group DMs
chat:write # Send messages
users:read # List users
users.profile:read # Read user profiles
files:read # List files
files:write # Upload files
reactions:read # Read reactions
reactions:write # Add/remove reactions
search:read # Search messages
```
### 3. Configure Redirect URI
Add your platform's callback URL under "OAuth & Permissions" → "Redirect URLs":
```
https://your-platform.com/oauth/slack/callback
```
### 4. Get Client Credentials
Note down your:
- Client ID
- Client Secret
## Environment Variables
The MCP server reads credentials from environment variables:
```bash
# Required
SLACK_ACCESS_TOKEN=xoxp-your-user-token
# Optional
SLACK_TEAM_ID=T0123456789
```
## OAuth 2.0 Flow (Platform Implementation)
### Step 1: Redirect User to Slack Authorization
```typescript
const SLACK_CLIENT_ID = 'your-client-id';
const REDIRECT_URI = 'https://your-platform.com/oauth/slack/callback';
const SCOPES = 'channels:read,channels:history,chat:write,users:read,files:read,files:write,reactions:read,reactions:write,search:read,groups:read,groups:history,im:read,im:history,mpim:read,mpim:history,users.profile:read';
const authUrl = `https://slack.com/oauth/v2/authorize?client_id=${SLACK_CLIENT_ID}&user_scope=${SCOPES}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&state=${generateRandomState()}`;
// Redirect user to authUrl
```
### Step 2: Handle OAuth Callback
```typescript
// In your callback handler
app.get('/oauth/slack/callback', async (req, res) => {
const { code, state } = req.query;
// Verify state to prevent CSRF
if (!verifyState(state)) {
return res.status(400).send('Invalid state');
}
// Exchange code for token
const response = await fetch('https://slack.com/api/oauth.v2.access', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
client_id: SLACK_CLIENT_ID,
client_secret: SLACK_CLIENT_SECRET,
code,
redirect_uri: REDIRECT_URI,
}),
});
const data = await response.json();
if (data.ok) {
// Save user token to your database
const userToken = data.authed_user.access_token; // xoxp-...
const userId = data.authed_user.id;
const teamId = data.team.id;
await db.saveSlackToken(currentUserId, {
token: userToken,
slackUserId: userId,
teamId: teamId,
});
res.redirect('/success');
} else {
res.status(400).send(`OAuth error: ${data.error}`);
}
});
```
### Step 3: Start MCP Server with User Token
```typescript
// When starting the MCP server for a user, inject their token as env var
const userSlackToken = await db.getSlackToken(currentUserId);
const mcpProcess = spawn('node', ['/path/to/slack-mcp/dist/index.js'], {
env: {
...process.env,
SLACK_ACCESS_TOKEN: userSlackToken,
},
});
```
## MCP Configuration
Add to your Claude Code configuration (`~/.claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"slack": {
"command": "node",
"args": ["/path/to/slack-mcp/dist/index.js"],
"env": {
"SLACK_ACCESS_TOKEN": "xoxp-your-token"
}
}
}
}
```
## Available Tools
### Channel Tools
| Tool | Description |
|------|-------------|
| `slack_list_channels` | List all accessible channels |
| `slack_get_channel_info` | Get channel details |
| `slack_get_channel_members` | Get channel member list |
### Message Tools
| Tool | Description |
|------|-------------|
| `slack_get_messages` | Get messages from a channel |
| `slack_get_thread_replies` | Get replies in a thread |
| `slack_send_message` | Send a message to a channel |
| `slack_reply_to_thread` | Reply to a thread |
| `slack_search_messages` | Search messages (requires user token) |
### User Tools
| Tool | Description |
|------|-------------|
| `slack_list_users` | List workspace users |
| `slack_get_user_info` | Get user details |
| `slack_get_user_profile` | Get user profile |
### File Tools
| Tool | Description |
|------|-------------|
| `slack_list_files` | List shared files |
| `slack_get_file_info` | Get file details |
| `slack_upload_file` | Upload a file |
### Reaction Tools
| Tool | Description |
|------|-------------|
| `slack_add_reaction` | Add emoji reaction |
| `slack_remove_reaction` | Remove emoji reaction |
| `slack_get_reactions` | Get message reactions |
## Example Usage
### List Channels
```json
{
"tool": "slack_list_channels",
"arguments": {
"types": "public_channel,private_channel",
"limit": 50
}
}
```
### Send Message
```json
{
"tool": "slack_send_message",
"arguments": {
"channel_id": "C1234567890",
"text": "Hello from MCP!"
}
}
```
### Search Messages
```json
{
"tool": "slack_search_messages",
"arguments": {
"query": "from:@user in:#channel important",
"count": 20
}
}
```
## Error Handling
The server returns structured error responses:
```json
{
"error": "Slack API Error (invalid_auth): Invalid authentication token."
}
```
Common error codes:
- `invalid_auth`: Token is invalid
- `token_revoked`: Token has been revoked
- `missing_scope`: Token lacks required scope
- `channel_not_found`: Channel doesn't exist
- `ratelimited`: Rate limit exceeded
## Security Considerations
- Never expose user tokens in client-side code
- Store tokens securely in your database (encrypted)
- Use HTTPS for all OAuth redirects
- Validate state parameter to prevent CSRF
- Rotate tokens periodically using refresh tokens
- Request only necessary scopes
## License
MIT
