npm package: @meepo-ab/slack-mcp
Description: Slack integration using Model Context Protocol
Author: Meepo AB
Latest version: 1.0.0

# Slack MCP (Model Context Protocol) Integration

The Slack MCP Server is an implementation of the Model Context Protocol (MCP) for interacting with Slack workspaces. It enables AI-driven collaboration by allowing Large Language Models (LLMs) to interact with Slack through MCP, providing programmatic access to Slack features for AI assistants like Claude.

## Features

This MCP server provides a comprehensive set of tools for interacting with Slack:

### Channel Management
- **List Channels** - View public and private channels
- **Create Channels** - Create new public or private channels
- **Join Channels** - Join public channels programmatically
- **Invite Users** - Add users to channels

### Messaging
- **Send Messages** - Post messages to channels or threads
- **Read Messages** - Retrieve message history from channels
- **Thread Interactions** - Create and participate in message threads
- **Reactions** - Add emoji reactions to messages

### User Operations
- **User Management** - List users, view profiles, and check presence
- **Direct Messaging** - Open and manage direct message channels
- **Group Direct Messaging** - Create and manage multi-person direct messages

## Configuration

### Prerequisites
- A Slack workspace with admin permissions
- A Slack bot token with required permissions

### Cursor MCP Configuration

To use this MCP server with Cursor, create a `.cursor/mcp.json` file in your project directory with the following configuration:

```json
{
  "mcpServers": {
    "slack-mcp": {
      "command": "npx",
      "args": [
        "@meepo-ab/slack-mcp"
      ],
      "env": {
        "SLACK_BOT_TOKEN": "your_slack_bot_token",
        "SLACK_TEAM_ID": "your_slack_team_id"
      }
    }
  }
}
```

Replace:
- `your_slack_bot_token` with your Slack Bot Token (xoxb-...)
- `your_slack_team_id` with your Slack Team ID

⚠️ **SECURITY NOTE**: The `.cursor/mcp.json` file contains sensitive credentials. Make sure to:
- Add `.cursor/mcp.json` to your `.gitignore` file to prevent accidentally committing it
- Never share this file with others

This configuration automatically downloads and runs the latest version of the Slack MCP Server without requiring any manual installation.

### Required Slack App Permissions

Your Slack bot needs the following OAuth scopes:

- `channels:read` - View public channel information
- `channels:history` - Read messages in public channels
- `groups:read` - View private channel information
- `groups:history` - Read messages in private channels
- `chat:write` - Post messages in channels the bot is in
- `chat:write.public` - Post messages to channels without joining them
- `im:write` - Send direct messages
- `im:read` - View direct message channels
- `im:history` - Read direct message history
- `mpim:write` - Send group direct messages
- `mpim:read` - View group direct message channels
- `mpim:history` - Read group direct message history
- `users:read` - View user information and presence
- `users:read.email` - Access user email addresses
- `reactions:write` - Add reactions to messages
- `channels:join` - Join public channels

## Available Tools

### Channel Operations

#### List Public Channels
- Tool: `slack_list_channels`
- Parameters:
  - `limit` (optional, number, default: 100)
  - `cursor` (optional, string)
- Required Scopes: `channels:read`

#### List Private Channels
- Tool: `slack_list_private_channels`
- Parameters:
  - `limit` (optional, number, default: 100)
  - `cursor` (optional, string)
- Required Scopes: `groups:read`

#### Create Channel
- Tool: `slack_create_channel`
- Parameters:
  - `name` (string)
  - `is_private` (optional, boolean, default: false)
  - `user_ids` (optional, string[])
- Required Scopes: `channels:write` (public), `groups:write` (private)

#### Join Channel
- Tool: `slack_join_channel`
- Parameters:
  - `channelId` (string)
- Required Scopes: `channels:join`

#### Invite to Channel
- Tool: `slack_invite_to_channel`
- Parameters:
  - `channelId` (string)
  - `userIds` (string[])
- Required Scopes: `channels:write` (public), `groups:write` (private)

### Message Operations

#### Get Channel History
- Tool: `slack_get_channel_history`
- Parameters:
  - `channelId` (string)
  - `limit` (optional, number, default: 100)
- Required Scopes: `channels:history` (public), `groups:history` (private), `im:history` (DMs), `mpim:history` (group DMs)

#### Post Message
- Tool: `slack_post_message`
- Parameters:
  - `channelId` (string)
  - `text` (string)
- Required Scopes: `chat:write` (when bot is in channel), `chat:write.public` (when bot is not in channel)

#### Get Thread Replies
- Tool: `slack_get_thread_replies`
- Parameters:
  - `channelId` (string)
  - `threadTs` (string)
- Required Scopes: `channels:history` (public), `groups:history` (private), `im:history` (DMs), `mpim:history` (group DMs)

#### Post Reply
- Tool: `slack_post_reply`
- Parameters:
  - `channelId` (string)
  - `threadTs` (string)
  - `text` (string)
- Required Scopes: `chat:write`

### User Operations

#### List Users
- Tool: `slack_list_users`
- Parameters:
  - `limit` (optional, number, default: 100)
  - `cursor` (optional, string)
- Required Scopes: `users:read`

#### Get User Profile
- Tool: `slack_get_user_profile`
- Parameters:
  - `userId` (string)
- Required Scopes: `users:read`

#### Get User Presence
- Tool: `slack_get_user_presence`
- Parameters:
  - `userId` (string)
- Required Scopes: `users:read`

### Reaction Operations

#### Add Reaction
- Tool: `slack_add_reaction`
- Parameters:
  - `channelId` (string)
  - `timestamp` (string)
  - `name` (string)
- Required Scopes: `reactions:write`

### Direct Messaging Operations

#### Open Direct Message
- Tool: `slack_open_dm`
- Parameters:
  - `userId` (string)
- Required Scopes: `im:write`

#### Open Group Direct Message
- Tool: `slack_open_group_dm`
- Parameters:
  - `userIds` (string[])
- Required Scopes: `mpim:write`

#### List Direct Messages
- Tool: `slack_list_dms`
- Parameters:
  - `limit` (optional, number, default: 100)
  - `cursor` (optional, string)
- Required Scopes: `im:read`

#### List Group Direct Messages
- Tool: `slack_list_group_dms`
- Parameters:
  - `limit` (optional, number, default: 100)
  - `cursor` (optional, string)
- Required Scopes: `mpim:read`

#### Get Direct Message History
- Tool: `slack_get_dm_history`
- Parameters:
  - `dmChannelId` (string)
  - `limit` (optional, number, default: 100)
- Required Scopes: `im:history` (DMs), `mpim:history` (group DMs)

## Example Workflows

### Team Collaboration:
- Ask the AI to send a status update to a team channel
- The AI can collect information and format a professional message
- The AI can manage follow-up discussions in threads

### Automated Responses:
- Configure the AI to respond to certain queries in channels
- The AI can detect questions and provide helpful responses
- The AI can direct users to appropriate resources

### User Engagement:
- Use the AI to run polls or gather feedback
- The AI can send direct messages to specific users
- The AI can summarize responses and provide insights

## Development

### Building from source
```bash
git clone https://gitlab.com/meepoab/ai-labs/mcp-servers/slack-mcp.git
cd slack-mcp
npm install
npm run build:cli
```

### Available Scripts
- `npm run build:cli` - Build the TypeScript code
- `npm run dev` - Watch for changes and rebuild automatically
- `npm test` - Run tests
- `npm run lint` - Lint the code
- `npm run format` - Format the code with Prettier

## License

MIT