# Slack MCP Server
A Model Context Protocol (MCP) server for searching Slack channels and messages.
## Features
- **list_channels** - List available Slack channels in the workspace
- **search_messages** - Search for messages across channels using text matching
- **get_channel_history** - Get message history from a specific channel
## Installation
### Using npx (Recommended)
No installation required. Add directly to your config:
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "github:nikhilchintawar/slack-mcp"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token-here"
}
}
}
}
```
**Claude Code** (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "github:nikhilchintawar/slack-mcp"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token-here"
}
}
}
}
```
### Manual Installation
```bash
# Clone the repository
git clone https://github.com/nikhilchintawar/slack-mcp.git
cd slack-mcp
# Install dependencies
npm install
# Build
npm run build
```
Then add to your config:
```json
{
"mcpServers": {
"slack": {
"command": "node",
"args": ["/absolute/path/to/slack-mcp/build/index.js"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token-here"
}
}
}
}
```
## Configuration
### Config File Locations
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Code:** `~/.claude/settings.json`
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SLACK_BOT_TOKEN` | Yes | Slack Bot User OAuth Token |
| `SLACK_CHANNELS` | No | Comma-separated list of allowed channels (restricts searches) |
| `SLACK_DEFAULT_CHANNEL` | No | Default channel ID for operations |
### Channel Restrictions
Use `SLACK_CHANNELS` to restrict which channels can be searched. When configured:
- Searches without a channel specified will search all allowed channels
- Searches with a specific channel will validate it's in the allowed list
- `get_channel_history` will only work with allowed channels
```json
{
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token",
"SLACK_CHANNELS": "general,engineering,support"
}
}
```
### Slack App Setup
1. Create a Slack App at https://api.slack.com/apps
2. Go to "OAuth & Permissions"
3. Add the following Bot Token Scopes:
- `channels:read` - List public channels
- `channels:history` - Read messages from public channels
- `groups:read` - List private channels (optional)
- `groups:history` - Read messages from private channels (optional)
4. Install the app to your workspace
5. Copy the "Bot User OAuth Token" (starts with `xoxb-`)
6. **Important:** Add the bot to each channel you want to search (right-click channel → "Open channel details" → "Integrations" → "Add apps")
## Usage Examples
Once configured, you can use natural language to interact with Slack:
- "List all channels in my Slack workspace"
- "Search for messages about deployment in #engineering"
- "Show me the last 50 messages from #general"
- "Find messages from @john about the API"
- "Search for error messages from last week"
## Available Tools
### `list_channels`
List available Slack channels in the workspace.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `includePrivate` | No | Include private channels (default: false) |
| `includeArchived` | No | Include archived channels (default: false) |
| `limit` | No | Max results (default: 100, max: 1000) |
### `search_messages`
Search for messages across Slack channels using text matching. Fetches channel history and filters by query.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search text (case-insensitive). Use `\|` for OR, spaces for AND |
| `channel` | No | Channel ID or name. If not set, searches all `SLACK_CHANNELS` |
| `after` | No | Search messages after date (YYYY-MM-DD or ISO 8601) |
| `before` | No | Search messages before date (YYYY-MM-DD or ISO 8601) |
| `limit` | No | Max results (default: 20, max: 100) |
**Query examples:**
- `error` - messages containing "error"
- `error warning` - messages containing both "error" AND "warning"
- `error | warning` - messages containing "error" OR "warning"
### `get_channel_history`
Get message history from a specific Slack channel.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `channel` | No | Channel ID (uses env var default) |
| `oldest` | No | Start time (Unix timestamp or ISO date) |
| `latest` | No | End time (Unix timestamp or ISO date) |
| `limit` | No | Max results (default: 100, max: 1000) |
| `includeThreadReplies` | No | Include thread replies (default: false) |
## Development
```bash
# Watch mode for development
npm run dev
# Build for production
npm run build
# Test with MCP Inspector
SLACK_BOT_TOKEN=xoxb-your-token \
npx @modelcontextprotocol/inspector node build/index.js
```
## License
MIT
