# Slack MCP Server

A Model Context Protocol (MCP) server for Slack integration, allowing Claude to interact with your Slack workspace. This server runs exclusively in Docker/Podman containers.

## Features

- Send messages to channels or users
- Send replies to message threads
- Search for messages across the workspace
- List all channels in workspace
- Get channel message history
- Get replies from message threads
- List all users in workspace

## Prerequisites

- Docker or Podman installed
- A Slack Bot Token (see Setup section)

## Setup

### 1. Create a Slack App

1. Go to https://api.slack.com/apps
2. Click "Create New App" → "From scratch"
3. Give it a name and select your workspace

### 2. Configure Bot Token Scopes

Go to OAuth & Permissions and add these Bot Token Scopes:
- `channels:read`
- `chat:write`
- `users:read`
- `channels:history`
- `groups:read`
- `groups:history`

### 3. Install the App

1. Click "Install to Workspace"
2. Copy the Bot User OAuth Token (starts with `xoxb-`)

### 4. Set Up Environment Variable

Create a `.env` file in the project root:
```bash
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
```

## Running with Docker

### Build the Image

```bash
docker build -t slack-mcp-server .
```

### Run the Container

```bash
docker run -i \
  -e SLACK_BOT_TOKEN=xoxb-your-bot-token-here \
  slack-mcp-server
```

### Using docker-compose

```bash
# Set your token in .env file first
docker-compose up
```

## Running with Podman

### Build the Image

```bash
podman build -t slack-mcp-server .
```

### Run the Container

```bash
podman run -i \
  -e SLACK_BOT_TOKEN=xoxb-your-bot-token-here \
  slack-mcp-server
```

### Using podman-compose

```bash
# Set your token in .env file first
podman-compose up
```

## Configuration with Claude Code

Add this to your Claude Code MCP settings file:

### Docker Configuration

```json
{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SLACK_BOT_TOKEN=xoxb-your-actual-bot-token-from-step-3",
        "slack-mcp-server"
      ]
    }
  }
}
```

### Podman Configuration

```json
{
  "mcpServers": {
    "slack": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SLACK_BOT_TOKEN=xoxb-your-actual-bot-token-from-step-3",
        "slack-mcp-server"
      ]
    }
  }
}
```

### Alternative: Using Environment File

```json
{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/.env",
        "slack-mcp-server"
      ]
    }
  }
}
```

## Available Tools

The server communicates via stdio and provides these tools:

- `send_message`: Send a message to a channel or user
- `send_thread_reply`: Send a reply to a message thread
- `search_messages`: Search for messages across the workspace (supports Slack search syntax)
- `list_channels`: List all workspace channels
- `get_channel_history`: Get recent messages from a channel
- `get_thread_replies`: Get all replies from a message thread
- `list_users`: List all workspace users

### Search Examples

The `search_messages` tool supports Slack's powerful search syntax:
- `"error message"` - Search for exact phrase
- `from:@username` - Messages from specific user
- `in:#channel` - Messages in specific channel
- `after:2024-01-01` - Messages after date
- `has:link` - Messages containing links
- Combine: `from:@john in:#general error` - Complex queries

## Development

### Build and Test Locally

```bash
# Build the image
docker build -t slack-mcp-server:dev .

# Run tests
docker run --rm slack-mcp-server:dev npm test
```

### Shell Access for Debugging

```bash
docker run -it --rm \
  -e SLACK_BOT_TOKEN=xoxb-your-token \
  --entrypoint /bin/sh \
  slack-mcp-server
```

## Security Features

- Multi-stage build for minimal image size
- Non-root user execution
- Read-only root filesystem
- No new privileges
- Resource limits configured in docker-compose
- Minimal Alpine Linux base image

## Troubleshooting

### Container exits immediately
Make sure you're running with `-i` (interactive) flag for stdin communication.

### Token not found
Verify your `SLACK_BOT_TOKEN` is correctly set in the environment or `.env` file.

### Permission errors
The container runs as a non-root user (nodejs). Ensure any mounted volumes have appropriate permissions.

## License

MIT