README.md•5.13 kB
# Slack MCP Server
A Model Context Protocol (MCP) server that provides Slack integration capabilities. This server follows clean architecture principles with proper separation of concerns.
## Features
- **List Channels**: Get all public channels in your workspace with pagination support
- **Post Messages**: Send messages to specific channels
- **Reply to Threads**: Reply to existing message threads
- **Add Reactions**: Add emoji reactions to messages
- **Get Channel History**: Retrieve recent messages from channels
- **Get Thread Replies**: Get all replies in a message thread
- **Parse Slack URLs**: Automatically extract thread details from Slack URLs
## Architecture
This project follows clean architecture principles:
```
src/
├── core/ # Domain layer
│ ├── interfaces/ # Interfaces and contracts
│ └── types/ # Type definitions
├── application/ # Application layer
│ ├── services/ # Business logic services
│ └── usecases/ # Use case implementations
├── infrastructure/ # Infrastructure layer
│ ├── server/ # Mcp server configuration
│ ├── clients/ # External API clients
│ └── storage/ # Storage implementations
├── presentation/ # Presentation layer
│ └── routes/ # API routes (if needed)
└── config/ # Configuration and dependency injection
```
## Setup
### 1. Slack App Configuration
First, create a Slack App and configure the required permissions:
1. Go to https://api.slack.com/apps
2. Create a new app or select existing one
3. Navigate to **OAuth & Permissions** → **Bot Token Scopes**
4. Add the following permissions:
```
channels:read - List channels
channels:history - Read public channel messages
groups:history - Read private channel/group messages
chat:write - Send messages
reactions:write - Add emoji reactions
```
5. Click **Install App to Workspace**
6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
### 2. Project Setup
1. **Install dependencies:**
```bash
npm install
```
2. **Build the project:**
```bash
npm run build
```
3. **Run the server:**
```bash
npm start
```
### 3. MCP Configuration
Add to your MCP client configuration (e.g., Cursor):
```json
{
"slack-mcp": {
"url": "http://localhost:3001/sse",
"env": {
"SLACK_TOKEN": "xoxb-your-bot-token-here"
}
}
}
```
## Development
- **Development mode:** `npm run dev`
- **Inspector mode:** `npm run inspector`
- **Clean build:** `npm run clean && npm run build`
## Token Management
All tools require a `token` parameter (Slack Bot Token). The token is passed directly to each tool call, ensuring secure and flexible authentication.
**Example usage:**
```javascript
await slack_list_channels({
limit: 50,
token: "xoxb-your-bot-token-here",
});
```
## Available Tools
### slack_list_channels
List public channels in the workspace with pagination.
**Parameters:**
- `limit` (optional): Maximum number of channels to return (default 100, max 200)
- `cursor` (optional): Pagination cursor for next page of results
- `token`: Slack bot token (required)
### slack_post_message
Post a new message to a Slack channel.
**Parameters:**
- `channel_id`: The ID of the channel to post to
- `text`: The message text to post
- `token`: Slack bot token (required)
### slack_reply_to_thread
Reply to a specific message thread in Slack.
**Parameters:**
- `channel_id`: The ID of the channel containing the thread
- `thread_ts`: The timestamp of the parent message
- `text`: The reply text
- `token`: Slack bot token (required)
### slack_add_reaction
Add a reaction emoji to a message.
**Parameters:**
- `channel_id`: The ID of the channel containing the message
- `timestamp`: The timestamp of the message to react to
- `reaction`: The name of the emoji reaction (without ::)
- `token`: Slack bot token (required)
### slack_get_channel_history
Get recent messages from a channel.
**Parameters:**
- `channel_id`: The ID of the channel
- `limit` (optional): Number of messages to retrieve (default 10)
- `token`: Slack bot token (required)
### slack_get_thread_replies
Get all replies in a message thread.
**Parameters:**
- `channel_id`: The ID of the channel containing the thread
- `thread_ts`: The timestamp of the parent message
- `token`: Slack bot token (required)
### slack_parse_url
Parse a Slack URL and automatically extract thread/message details.
**Parameters:**
- `url`: Slack URL (e.g., https://workspace.slack.com/archives/CHANNEL_ID/pTIMESTAMP)
- `token`: Slack bot token (required)
**Example:**
```javascript
await slack_parse_url({
url: "https://workspace.slack.com/archives/CHANNEL_ID/pTIMESTAMP",
token: "xoxb-your-bot-token-here",
});
```
This tool automatically:
- Parses the URL to extract workspace, channel ID, and message timestamp
- Fetches channel history
- Retrieves thread replies if available
- Returns formatted message details
## License
MIT