Skip to main content
Glama
Slack MCP Server

Slack MCP Server

by ubie-oss
README.md
# slack-mcp-server

A [MCP(Model Context Protocol)](https://www.anthropic.com/news/model-context-protocol) server for accessing Slack API. This server allows AI assistants to interact with the Slack API through a standardized interface.

## Transport Support

This server supports both traditional and modern MCP transport methods:

- **Stdio Transport** (default): Process-based communication for local integration
- **Streamable HTTP Transport**: HTTP-based communication for web applications and remote clients

## Features

Available tools:

- `slack_list_channels` - List public channels in the workspace with pagination
- `slack_post_message` - Post a new message to a Slack channel. `text` is standard Markdown that Slack renders; set `format: "slack_mrkdwn"` to write Slack mrkdwn instead
- `slack_reply_to_thread` - Reply to a specific message thread in Slack. Takes `text` and `format` like `slack_post_message`
- `slack_add_reaction` - Add a reaction emoji to a message
- `slack_get_channel_history` - Get recent messages from a channel
- `slack_get_thread_replies` - Get all replies in a message thread
- `slack_get_users` - Retrieve basic profile information of all users in the workspace
- `slack_get_user_profiles` - Get multiple users' profile information in bulk (efficient for batch operations)
- `slack_search_messages` - Search for messages in the workspace with powerful filters:
  - Basic query search
  - Location filters: `in_channel`
  - User filters: `from_user`, `with`
  - Date filters: `before` (YYYY-MM-DD), `after` (YYYY-MM-DD), `on` (YYYY-MM-DD), `during` (e.g., "July", "2023")
  - Content filters: `has` (emoji reactions), `is` (saved/thread)
  - Sorting options by relevance score or timestamp

## Quick Start

### Installation

```bash
npm install @ubie-oss/slack-mcp-server
```

NOTE: Its now hosted in GitHub Registry so you need your PAT.

### Configuration

You need to set the following environment variables:

- `SLACK_BOT_TOKEN`: Slack Bot User OAuth Token
- `SLACK_USER_TOKEN`: Slack User OAuth Token (required for some features like message search)
- `SLACK_SAFE_SEARCH` (optional): When set to `true`, message searches use Slack's Real-time Search API with `channel_types: ["public_channel"]`. The user token must have the `search:read.public` scope. The public-channel restriction applies before results are selected and paginated; clients cannot override it. This option affects message search, not the permissions of other tools.

You can also create a `.env` file to set these environment variables:

```
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_USER_TOKEN=xoxp-your-user-token
SLACK_SAFE_SEARCH=true  # Optional: Enable safe search mode
```

### Public message search

With `SLACK_SAFE_SEARCH=true`, `slack_search_messages` calls [`assistant.search.context`](https://docs.slack.dev/reference/methods/assistant.search.context/) using the **user token**, public channels only, message results only, and keyword search. It does not call legacy `search.messages`, including when the new API is unavailable or the token lacks a required scope.

The search tool keeps the existing keyword, channel, user, date and sorting fields. Public mode uses `limit` (1–20, default 20) and `cursor` instead of `count` and `page`. Pass `next_cursor` back with the same query and filters to read another page. An empty cursor marks the end of the results.

```json
{"query":"project update","limit":20,"cursor":"cursor-from-the-previous-response"}
```

Each successful MCP call returns a single text content block containing this JSON contract. It has no total counts, page numbers, ranking metadata, contextual messages or other result types. `channel.name` and `user` may be omitted; `next_cursor` is always a string.

```json
{
  "contract": "slack-public-search-v1",
  "messages": {
    "matches": [{
      "channel": {"id": "C1234567", "name": "general"},
      "text": "Public project update",
      "ts": "1234567890.123456",
      "user": "U1234567",
      "permalink": "https://example.slack.com/archives/C1234567/p1234567890123456"
    }]
  },
  "next_cursor": ""
}
```

To upgrade an existing safe-search deployment:

1. Add the `search:read.public` **user** scope to the Slack app and reauthorize it. A token with only legacy `search:read` is insufficient. Do not share tokens in configuration examples or logs.
2. Deploy this server with safe search enabled. Verify a public query and a subsequent cursor request. A `missing_scope` error explains the required scope; other API failures do not trigger a legacy fallback.
3. Upgrade clients to accept the `slack-public-search-v1` response and cursor input. Clients that depend on a public-only boundary should reject legacy responses instead of forwarding their metadata.

When `SLACK_SAFE_SEARCH` is unset or false, the existing legacy search API, `count`/`page` inputs and response shape remain unchanged.

### Usage

#### Start the MCP server

**Stdio Transport (default)**:
```bash
npx @ubie-oss/slack-mcp-server
```

**Streamable HTTP Transport**:
```bash
npx @ubie-oss/slack-mcp-server -port 3000
```

You can also run the installed module with node:
```bash
# Stdio transport
node node_modules/.bin/slack-mcp-server

# HTTP transport  
node node_modules/.bin/slack-mcp-server -port 3000
```

**Command Line Options**:
- `-port <number>`: Start with Streamable HTTP transport on specified port
- `-h, --help`: Show help message

#### Client Configuration

**For Stdio Transport (Claude Desktop, etc.)**:

```json
{
  "slack": {
    "command": "npx",
    "args": [
      "-y",
      "@ubie-oss/slack-mcp-server"
    ],
    "env": {
      "NPM_CONFIG_//npm.pkg.github.com/:_authToken": "<your-github-pat>",
      "SLACK_BOT_TOKEN": "<your-bot-token>",
      "SLACK_USER_TOKEN": "<your-user-token>",
      "SLACK_SAFE_SEARCH": "true"
    }
  }
}
```

**For Streamable HTTP Transport (Web applications)**:

Start the server:
```bash
SLACK_BOT_TOKEN=<your-bot-token> SLACK_USER_TOKEN=<your-user-token> npx @ubie-oss/slack-mcp-server -port 3000
```

Connect to: `http://localhost:3000/mcp`

See [examples/README.md](examples/README.md) for detailed client examples.

## Implementation Pattern

This server adopts the following implementation pattern:

1. Define request/response using Zod schemas
   - Request schema: Define input parameters
   - Response schema: Define responses limited to necessary fields

2. Implementation flow:
   - Validate request with Zod schema
   - Call Slack WebAPI
   - Parse response with Zod schema to limit to necessary fields
   - Return as JSON

For example, the `slack_list_channels` implementation parses the request with `ListChannelsRequestSchema`, calls `slackClient.conversations.list`, and returns the response parsed with `ListChannelsResponseSchema`.

## Development

### Available Scripts

- `npm run dev` - Start the server in development mode with hot reloading
- `npm run build` - Build the project for production
- `npm run start` - Start the production server
- `npm run lint` - Run linting checks (ESLint and Prettier)
- `npm test` - Run the message-search boundary tests with Node's test runner
- `npm run fix` - Automatically fix linting issues

### Contributing

1. Fork the repository
2. Create your feature branch
3. Run tests and linting: `npm run lint`
4. Commit your changes
5. Push to the branch
6. Create a Pull Request

TDQS

A3.6/5.0

Scored across 11 tools

Disambiguation4/5

Most tools target distinct actions (post, reply, react, list, search), and the history-vs-search-messages pair is explicitly disambiguated in the descriptions. The main overlap is slack_get_users (all users, basic info) versus slack_get_user_profiles (bulk profile info) versus slack_search_users, where the boundary between the first two is unclear.

Naming Consistency5/5

All tools use a uniform slack_<verb>_<noun> snake_case convention (slack_post_message, slack_list_channels, slack_search_users), with verbs chosen sensibly for the action. No mixed casing or inconsistent prefixes.

Tool Count5/5

Eleven tools is well within a reasonable range for a Slack integration and each tool maps to a recognizable Slack operation. Nothing feels padded or missing at the count level.

Completeness3/5

Core read/write workflows (post, reply, react, read history/threads, search, list channels/users) are covered, but the message lifecycle is incomplete: no update_message, delete_message, or remove_reaction, and there is no direct-message or channel-management (create/join) coverage. These are notable gaps that would force agents into dead ends for common Slack tasks.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues