Slack MCP Server

Give your AI agent full Slack access — and structured workflow output the AI can actually use. No app registration, no admin approval, no OAuth. One command, 21 tools, works with any MCP client.

npx -y @jtalk22/slack-mcp --setup

Slack MCP Server Demo

[▶ Watch the demo](https://jtalk22.github.io/slack-mcp-server/public/demo-video.html) — 7 scenarios, from 47 unreads to inbox zero, without opening Slack.

Ask your AI to catch you up on #engineering from the last 24 hours. Search for that deployment thread from last week. Find the printer admin PIN nobody can remember. Send a reply. All from your editor.

Interactive demo · Latest release

Why This Exists

Slack's official MCP server is OAuth-first and can require a registered app, admin approval, or client compatibility workarounds. See the tracked Claude Code/GitHub Copilot compatibility discussion. Screenshotting messages is not a workflow.

This server uses your browser's session tokens instead. If you can see it in Slack, your AI agent can see it too. No app install, no scopes, no admin.

Session-token transport: No bot user appears in the workspace admin panel, no app install shows up, no audit trail entry is created. Your AI agent operates with the same workspace footprint as your browser tab — nothing more, nothing less.

OAuth vs Chrome DB Decryption

Workflow Primitives

Introduced in 4.2. Save a workflow profile that binds a workflow_kind to channels + priority people + retention + cadence. Stored locally at ~/.slack-mcp-workflows.json. The hosted brain at mcp.revasserlabs.com reads these profiles and returns structured JSON per workflow_kind — downstream automation (Linear, Notion, status dashboards) consumes the JSON directly.

Six prebuilt templates ship with the package:

npx -y @jtalk22/slack-mcp --apply-template oncall-handoff --channels C012345,C067890

Available templates: oncall-handoff, support-triage, exec-monday, sprint-tracker, customer-feedback, incident-room. The structural primitives (slack_workflow_save, slack_workflows) are free forever in OSS; the hosted brain is $0 to start (no card) and $9/mo Pro for unlimited AI tools (scheduled morning catch-up DM rolling out Q2 2026).

Quick Start per Client

<details> <summary><strong>Claude Desktop / Claude Code</strong></summary>

Add to ~/.claude.json or Claude Desktop settings:

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

</details>

<details> <summary><strong>Windsurf</strong></summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

</details>

<details> <summary><strong>Gemini CLI</strong></summary>

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

</details>

<details> <summary><strong>Codex CLI</strong></summary>

Add to ~/.codex/config.toml:

[mcp_servers.slack]
command = "npx"
args = ["-y", "@jtalk22/slack-mcp"]

Or via CLI: codex mcp add slack -- npx -y @jtalk22/slack-mcp </details>

Tools

21 tools total: 12 read-only Slack, 4 write-path Slack, 2 workflow profile primitives (1 local-write, 1 read-only), 3 hosted stubs. All carry MCP safety annotations.

\* slack_refresh_tokens modifies local token file only.

† Hosted stubs return a structured upgrade payload (signup_url, free_tier_quota, pro_value_prop) — no Slack write occurs from OSS. Activate the brain at mcp.revasserlabs.com (free tier, no card).

‡ Also accepts include_rich_message_fields to return attachments, blocks, files, reactions, and metadata — see Rich Message Fields.

Install

Node.js 20+

npx -y @jtalk22/slack-mcp --setup

The setup wizard handles token extraction and validation.

After setup, have your client run slack_health_check — a workspace name in the response confirms you are connected.

<details> <summary><strong>Claude Desktop (macOS)</strong></summary>

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@jtalk22/slack-mcp"]
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop (Windows/Linux)</strong></summary>

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@jtalk22/slack-mcp"],
      "env": {
        "SLACK_TOKEN": "xoxc-your-token",
        "SLACK_COOKIE": "xoxd-your-cookie"
      }
    }
  }
}

Windows/Linux users must provide tokens via env since auto-refresh is macOS-only.

</details>

<details> <summary><strong>Claude Code</strong></summary>

Add to ~/.claude.json:

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jtalk22/slack-mcp"]
    }
  }
}

Or via CLI: claude mcp add slack -- npx -y @jtalk22/slack-mcp

</details>

<details> <summary><strong>Cursor / Copilot / Other MCP clients</strong></summary>

Any client that supports stdio MCP servers works. Add to your client's MCP config:

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@jtalk22/slack-mcp"],
    "env": {
      "SLACK_TOKEN": "xoxc-your-token",
      "SLACK_COOKIE": "xoxd-your-cookie"
    }
  }
}

On macOS, tokens are auto-extracted from Chrome — env block is optional.

</details>

<details> <summary><strong>Claude Web / Remote MCP</strong></summary>

Hosted tiers at mcp.revasserlabs.com:

</details>

<details> <summary><strong>Docker</strong></summary>

docker pull ghcr.io/jtalk22/slack-mcp-server:latest

{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-v", "~/.slack-mcp-tokens.json:/root/.slack-mcp-tokens.json",
               "ghcr.io/jtalk22/slack-mcp-server"]
    }
  }
}

</details>

Restart your client after configuration. Full setup: docs/SETUP.md

How It Works

Session tokens (xoxc- + xoxd-) from your browser. If you can see it in Slack, this server can see it too.

Token persistence — four-layer fallback:

1. Environment variables (SLACK_TOKEN, SLACK_COOKIE)
2. Token file (~/.slack-mcp-tokens.json, chmod 600)
3. macOS Keychain (encrypted)
4. Chrome auto-extraction (macOS)

Tokens expire. The server notices before you do — proactive health monitoring, automatic refresh on macOS, warnings when tokens age out. File writes are atomic (temp file → chmod → rename) to prevent corruption. Concurrent refresh attempts are mutex-locked.

<details> <summary><strong>What's New in 4.2.0</strong></summary>

• Workflow primitives — slack_workflow_save + slack_workflows bind a workflow_kind (incident_room, exec_brief, support_inbox, product_launch_watch, custom) to channels, priority people, retention, and cadence. The hosted brain returns structured JSON per kind — incident_room returns {incident_summary, timeline, open_risks, owner_gaps, next_actions}, exec_brief returns {summary, decisions, risks, asks, action_items}. Downstream automation (Linear, Notion, dashboards) consumes the JSON directly.
• Discoverable upgrade stubs — slack_smart_search, slack_catch_me_up, slack_triage appear in OSS as upgrade payloads pointing at the hosted brain. Response shape is {signup_url, free_tier_quota, pro_value_prop} — no interruptions, the AI routes the user cleanly.
• Six prebuilt templates — apply with npx -y @jtalk22/slack-mcp --apply-template <name> --channels C012,C034. Names: oncall-handoff, support-triage, exec-monday, sprint-tracker, customer-feedback, incident-room. Read them, fork them, edit them — they're JSON profiles.
• Setup wizard hosted bridge — six in-wizard moments surface the hosted free tier (no card) where it matches the user's pain. Stays out of the way otherwise.
• Prior reliability fixes carried forward — LevelDB token extraction, multi-profile enumeration, and explicit SIGTERM/SIGINT/SIGHUP/stdin shutdown handlers ship in 4.2.0 too.

Full release notes on GitHub releases/latest.

</details>

Rich Message Fields

Added in 4.4.0. The four read tools marked ‡ above accept include_rich_message_fields: true, which surfaces the parts of a message that live outside text — attachments, blocks, files, reactions, metadata, plus subtype/bot_id/app_id (automated/bot/app markers) and team (workspace id).

An attachment-only alert reads as empty without the flag:

{ "ts": "1767368030.607599", "user": "incident-bot", "text": "" }

With include_rich_message_fields: true, the content is surfaced:

{
  "ts": "1767368030.607599",
  "user": "incident-bot",
  "text": "",
  "subtype": "bot_message",
  "bot_id": "B012345",
  "attachments": [{ "title": "PagerDuty", "text": "P1 — API latency > 2s" }]
}

Output shape only — no extra permissions. blocks can be large, so it is opt-in per call to keep client context lean. For the full developer payload inside metadata, also set include_all_metadata: true (an independent Slack flag).

slack_search_messages accepts the flag, but Slack's search API does not return rich fields on matches — read full content with slack_conversations_history or slack_get_thread on the match's channel and timestamp.

Patch by @rvandam (#143).

Hosted HTTP Mode

For remote MCP endpoints (Cloudflare Worker, VPS, etc.):

SLACK_TOKEN=xoxc-... \
SLACK_COOKIE=xoxd-... \
SLACK_MCP_HTTP_AUTH_TOKEN=change-this \
SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai \
node src/server-http.js

Details: docs/DEPLOYMENT-MODES.md

Troubleshooting

Tokens expired: Run npx -y @jtalk22/slack-mcp --setup or use slack_refresh_tokens (macOS). To prevent silent expiration during long Claude-idle windows, set up the optional token-refresh LaunchAgent.

DMs not showing: Use slack_list_conversations with discover_dms=true.

Client not seeing tools: Check JSON syntax in config, restart client fully.

More: docs/TROUBLESHOOTING.md

Docs

• Setup Guide
• API Reference
• Roadmap
• Architecture
• Deployment Modes
• Use Case Recipes
• Troubleshooting
• Compatibility

Security

• Token files: chmod 600 (owner-only)
• macOS Keychain encrypted backup
• Web server binds to localhost only
• API keys: crypto.randomBytes
• See SECURITY.md

Contributing

PRs welcome. Run node --check on modified files before submitting.

License

MIT — See LICENSE

Disclaimer

Not affiliated with Slack Technologies, Inc. Uses browser session credentials — check your workspace's acceptable use policy.

Hosted version live at mcp.revasserlabs.com: Free tier (no card), $9/mo Pro, $49/mo Team flat, Ops from $199/mo. Hosted owns the AI brain (smart_search, catch_me_up, triage), the scheduled morning catch-up DM at 8am workspace time (rolling out Q2 2026), permanent OAuth (no 2-week token rotation), 90-day Vectorize retention, and shared workflow profiles. The OSS package owns local stdio + the 16 Slack tools (12 read, 4 write) + workflow profile primitives (slack_workflow_save, slack_workflows). The 3 paid stubs (slack_smart_search, slack_catch_me_up, slack_triage) appear in OSS as discoverable upgrade prompts.