Slack MCP Server

A Slack MCP server for Claude Code that provides full messaging, channels, search, and threads across multiple Slack workspaces.

Features

• 12 tools — channels, messages, threads, DMs, reactions, search, file upload

• Multi-workspace — connect as many Slack workspaces as you need

• Dual token support — bot tokens and user tokens, with automatic preference

• Post as yourself — user tokens make messages appear from you, not a bot

• Full search — search_messages works with user tokens (no limitations)

• Env-var tokens — no secrets in config files or the repo

• Channel name resolution — use #general or general, not just IDs

Related MCP server: Slack Search MCP Server

Quick Start

1. Clone and install

git clone https://github.com/coreyepstein/slack-mcp.git
cd slack-mcp
npm install

2. Create a Slack App

1. Go to api.slack.com/apps and click Create New App > From scratch

2. Name it (e.g. "Claude MCP") and select your workspace

3. Go to OAuth & Permissions and add scopes (see Scopes below)

4. Click Install to Workspace

5. Copy the Bot User OAuth Token (xoxb-...)

6. Optionally, copy the User OAuth Token (xoxp-...) — see Token Types

3. Configure workspaces

cp workspaces.example.json workspaces.json

Edit workspaces.json with your workspace name and team ID. Tokens are not stored here:

{
  "workspaces": [
    {
      "name": "my-company",
      "team_id": "T_YOUR_TEAM_ID"
    }
  ],
  "default": "my-company"
}

Find your team ID by running npm run auth -- --setup or from your Slack workspace URL settings.

4. Set token environment variables

Tokens are passed via environment variables, never stored in files. The naming convention is:

SLACK_TOKEN_{NAME}_BOT   →  Bot token (xoxb-...)
SLACK_TOKEN_{NAME}_USER  →  User token (xoxp-...)

Where {NAME} is the workspace name uppercased with non-alphanumeric characters replaced by underscores.

Examples:

5. Add to Claude Code

Add to your project .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/slack-mcp/src/server.ts"],
      "env": {
        "SLACK_TOKEN_MY_COMPANY_BOT": "xoxb-your-bot-token",
        "SLACK_TOKEN_MY_COMPANY_USER": "xoxp-your-user-token"
      }
    }
  }
}

For multiple workspaces, add all tokens to the same env block:

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/slack-mcp/src/server.ts"],
      "env": {
        "SLACK_TOKEN_VOYAGE_BOT": "xoxb-...",
        "SLACK_TOKEN_VOYAGE_USER": "xoxp-...",
        "SLACK_TOKEN_INDIGO_BOT": "xoxb-...",
        "SLACK_TOKEN_INDIGO_USER": "xoxp-..."
      }
    }
  }
}

Important: Use the absolute path to src/server.ts. Never commit tokens to any tracked file.

6. Verify setup

npm run auth:check

This validates all configured tokens against the Slack API and reports their status.

7. Invite the bot

In each Slack channel you want to access, invite the bot:

/invite @Claude MCP

This is required for the bot token to read/write in channels. User tokens can access any channel the token owner is already a member of.

Token Types

This server supports two types of Slack tokens per workspace:

Bot Token (xoxb-...)

• Created when you install a Slack App to a workspace

• Messages appear as the app (e.g. "Claude MCP"), not as a person

• Must be explicitly invited to channels with /invite

• Cannot use search:read (Slack API limitation)

• Good for: automated notifications, bot-style interactions

User Token (xoxp-...)

• Generated from the User OAuth Token on the OAuth & Permissions page

• Messages appear as the token owner (e.g. "Corey Epstein") — your real name and avatar

• Has access to any channel the token owner is a member of

• Required for search_messages (search:read scope)

• Good for: acting as yourself, search, accessing channels without /invite

How tokens are selected

The server automatically selects the best token for each operation:

You can start with just a bot token and add a user token later. All operations except search_messages work with either token type.

Post as User

When a user token (xoxp-...) is configured, all messages sent through the server appear as if you sent them — your name, your profile picture, your identity. This applies to:

• send_message — channel messages show your name

• reply_thread — thread replies show your name

• send_dm — DMs come from you, not a bot

This happens automatically. The Slack API posts as the token owner when using a user token. No special configuration or as_user parameter is needed.

If only a bot token is available, messages appear as the Slack App instead.

Scopes

Bot Token Scopes

Add these under OAuth & Permissions > Bot Token Scopes in your Slack App:

User Token Scopes

Add these under OAuth & Permissions > User Token Scopes for full functionality:

After adding user token scopes, click Reinstall to Workspace to generate the user token.

Tools

All tools accept an optional workspace parameter (name or team ID). If omitted, uses the default workspace from workspaces.json.

Multi-Workspace

Configure multiple workspaces in workspaces.json and set tokens for each:

{
  "workspaces": [
    { "name": "voyage", "team_id": "T7V83HY5B" },
    { "name": "indigo", "team_id": "T_INDIGO_ID" }
  ],
  "default": "voyage"
}

Then use the workspace parameter in any tool:

send_message(channel: "general", text: "hello", workspace: "voyage")
send_message(channel: "team", text: "hello", workspace: "indigo")

If workspace is omitted, uses the default from workspaces.json.

Auth CLI

The auth CLI helps with setup and health checks:

# Interactive setup — walks through token configuration
npm run auth -- --setup

# Health check — validates all tokens for all workspaces
npm run auth:check

The --check command tests each token against the Slack API and reports:

Workspace Health Check:
──────────────────────────────────────────────────────────────────────────
  Workspace: voyage (default)
    Bot token:  + connected as @claude-mcp in Voyage
    User token: + connected as @corey in Voyage

  Workspace: indigo
    Bot token:  + connected as @claude-mcp in Indigo
    User token: - missing (optional — needed for search:read)
                  Set env: SLACK_TOKEN_INDIGO_USER=xoxp-...

E2E Verification

An end-to-end verification script is included at scripts/verify-e2e.ts:

npx tsx scripts/verify-e2e.ts

# Or with a specific test channel:
TEST_CHANNEL=bot-testing npx tsx scripts/verify-e2e.ts

This verifies token connectivity, message posting identity, search functionality, and bot-token fallback across all configured workspaces.

Troubleshooting

Security

Token in git history: An earlier version of this repo stored a Slack bot token in workspaces.json. That token has been rotated and is no longer valid, but it may still appear in git commit history. If you forked or cloned this repo before the token was removed, the old token in your local history is already invalidated.

Best practice: Always pass tokens via environment variables in the .mcp.json env block. Never commit tokens to workspaces.json or any other tracked file. The .gitignore excludes workspaces.json to prevent accidental commits.

Architecture

src/
  server.ts           — MCP server entry point
  config.ts           — workspace + token resolution from env vars
  auth.ts             — setup and health check CLI
  slack/
    client.ts         — Slack Web API wrapper with dual-token client caching
    types.ts          — shared TypeScript types
  tools/
    *.ts              — one file per MCP tool (12 tools)
scripts/
  verify-e2e.ts       — end-to-end verification script

License

MIT