npm package: @plugix/mcp-slack
Description: MCP Server for Slack - Messages, Channels, User management
Author: Plugix
Latest version: 0.1.0

# @plugix/mcp-slack

MCP server for Slack workspace integration - messages, channels, and user management.

## Features

- **list_channels** - List channels in the workspace
- **get_channel_history** - Get message history from a channel
- **send_message** - Send a message to a channel (with confirmation)
- **list_users** - List users in the workspace
- **get_user_info** - Get detailed user information
- **search_messages** - Search messages across the workspace
- **upload_file** - Upload a file to a channel (with confirmation)
- **create_channel** - Create a new channel (with confirmation)

## Installation

```bash
npm install @plugix/mcp-slack
```

Or run directly:

```bash
npx @plugix/mcp-slack
```

## Configuration

Set environment variables:

```env
# Plugix API connection
API_URL=wss://api.plugix.ai
API_TOKEN=plx_live_your_token_here

# Slack Bot Token (required)
SLACK_BOT_TOKEN=xoxb-your-bot-token
```

### Getting a Slack Bot Token

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
2. Navigate to **OAuth & Permissions**
3. Add the required Bot Token Scopes (see below)
4. Install the app to your workspace
5. Copy the **Bot User OAuth Token** (starts with `xoxb-`)

## Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Docker

```bash
docker build -t plugix-mcp-slack .
docker run --env-file .env plugix-mcp-slack
```

### Claude Desktop Integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["@plugix/mcp-slack"],
      "env": {
        "API_URL": "wss://api.plugix.ai",
        "API_TOKEN": "plx_live_your_token",
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token"
      }
    }
  }
}
```

## Tools Reference

### list_channels

List channels in the Slack workspace.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| exclude_archived | boolean | Exclude archived channels (default: true) |
| limit | number | Maximum channels to return (default: 100) |
| types | string | Channel types: public_channel, private_channel, mpim, im |

**Example:**

```json
{
  "name": "list_channels",
  "arguments": {
    "limit": 50,
    "types": "public_channel"
  }
}
```

### get_channel_history

Get message history from a channel.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| channel_id | string | Yes | Channel ID (e.g., C1234567890) |
| limit | number | No | Max messages to return (default: 50) |
| oldest | string | No | Only messages after this Unix timestamp |
| latest | string | No | Only messages before this Unix timestamp |

**Example:**

```json
{
  "name": "get_channel_history",
  "arguments": {
    "channel_id": "C1234567890",
    "limit": 20
  }
}
```

### send_message

Send a message to a Slack channel. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| channel_id | string | Yes | Channel ID to send to |
| text | string | Yes | Message text (supports Slack markdown) |
| thread_ts | string | No | Reply in thread (parent message ts) |
| confirmed | boolean | Yes | Must be `true` to send |

**Example:**

```json
{
  "name": "send_message",
  "arguments": {
    "channel_id": "C1234567890",
    "text": "Hello from the AI assistant!",
    "confirmed": true
  }
}
```

### list_users

List users in the workspace.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| limit | number | Max users to return (default: 200) |

### get_user_info

Get detailed information about a specific user.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | string | Yes | User ID (e.g., U1234567890) |

**Example:**

```json
{
  "name": "get_user_info",
  "arguments": {
    "user_id": "U1234567890"
  }
}
```

### search_messages

Search messages across the workspace.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | Yes | Search query (supports Slack modifiers) |
| count | number | No | Max results (default: 20) |
| sort_by | string | No | Sort by: score or timestamp |
| sort_dir | string | No | Sort direction: asc or desc |

**Search Modifiers:**

- `from:@username` - Messages from a specific user
- `in:#channel` - Messages in a specific channel
- `has:link` - Messages with links
- `has:emoji` - Messages with emoji
- `before:2024-01-01` - Messages before a date
- `after:2024-01-01` - Messages after a date

**Example:**

```json
{
  "name": "search_messages",
  "arguments": {
    "query": "from:@john project deadline",
    "count": 10,
    "sort_by": "timestamp"
  }
}
```

### upload_file

Upload a file to a Slack channel. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| channel_id | string | Yes | Channel ID |
| content | string | Yes | File content |
| filename | string | Yes | Filename (e.g., report.txt) |
| title | string | No | File title |
| initial_comment | string | No | Message with the file |
| thread_ts | string | No | Upload to thread |
| confirmed | boolean | Yes | Must be `true` to upload |

**Example:**

```json
{
  "name": "upload_file",
  "arguments": {
    "channel_id": "C1234567890",
    "content": "Report data here...",
    "filename": "report.txt",
    "title": "Monthly Report",
    "initial_comment": "Here's the monthly report",
    "confirmed": true
  }
}
```

### create_channel

Create a new Slack channel. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | Yes | Channel name (lowercase, no spaces) |
| is_private | boolean | No | Create as private (default: false) |
| confirmed | boolean | Yes | Must be `true` to create |

**Example:**

```json
{
  "name": "create_channel",
  "arguments": {
    "name": "project-alpha",
    "is_private": false,
    "confirmed": true
  }
}
```

## Required Bot Token Scopes

Add these scopes to your Slack app under **OAuth & Permissions**:

### Channels

- `channels:read` - View basic channel information
- `channels:history` - View messages in public channels
- `channels:write` - Create and manage public channels

### Private Channels (if needed)

- `groups:read` - View private channels
- `groups:history` - View messages in private channels
- `groups:write` - Create and manage private channels

### Direct Messages (if needed)

- `im:read` - View direct messages
- `im:history` - View direct message history
- `mpim:read` - View group direct messages
- `mpim:history` - View group direct message history

### Messages

- `chat:write` - Send messages
- `files:write` - Upload files

### Users

- `users:read` - View users
- `users:read.email` - View user email addresses

### Search

- `search:read` - Search messages

## Testing

```bash
npm test
```

## License

MIT