npm version npm weekly downloads CI MCP Registry npm provenance signed

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

_{▶ Watch the full 3:24 demo — with chapters · interactive demo · setup guide}

Why no OAuth · Install · The 21 tools · Workflows · Token storage · Hosted

The trick: session tokens, not OAuth

Slack's official MCP server is OAuth-first — a registered app, admin approval, and (for several clients) compatibility workarounds that don't exist yet (see the tracked Claude Code / Copilot DCR discussion). For a lot of people the "integration" quietly degrades into screenshotting messages into a chat window. That isn't an integration.

So this server does the obvious thing instead: it reads the xoxc- + xoxd- session tokens your browser is already holding and speaks Slack's own API with them. No app install, no scopes to request, no admin in the loop — and because there's no bot user and no installed app, nothing appears in the workspace admin panel. Your agent's footprint is exactly your open browser tab's: no more, no less.

_{Same permissions either way — your agent sees exactly what you see. The difference is who has to approve it.}

Watch it run

_{A real session at 2× — unread counts → history pull → the briefing. Full 3:24 with chapters →}

Install

Node.js 20+. One command extracts your tokens, validates them, and remembers where to keep them:

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

Register the server with your client, restart it, then ask your agent to run slack_health_check — a workspace name in the reply means you're live. Pick your client:

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

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

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

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

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

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

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

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"]
    }
  }
}

Full walkthrough — including the optional keep-tokens-fresh LaunchAgent — in docs/SETUP.md.

The 21 tools

Every workspace write-path tool carries an MCP destructive annotation so clients can gate it.

_{* slack_refresh_tokens writes the local token file only. † Hosted stubs return a structured upgrade payload (signup_url, free_tier_quota, pro_value_prop) — no Slack call happens from OSS. ‡ Accepts include_rich_message_fields — see Rich message fields.}

Workflows: Slack in, typed JSON out

Reading messages is table stakes. The primitives turn Slack into a typed data source your automation can consume directly. Bind a workflow_kind to a set of channels, priority people, retention, and cadence with slack_workflow_save (stored locally at ~/.slack-mcp-workflows.json). The hosted brain reads those profiles and returns structured JSON per kind — no prompt-parsing, no scraping, feed it straight into Linear, Notion, or a status dashboard.

Six ready-to-fork templates ship in the box:

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

oncall-handoff · support-triage · exec-monday · sprint-tracker · customer-feedback · incident-room — plain JSON profiles you can read and edit. The primitives (slack_workflow_save, slack_workflows) are free forever in OSS; only the AI summarization runs on the hosted brain.

Copy-paste prompt recipes — summarize a channel, search for decisions, export a thread — live in docs/USE_CASE_RECIPES.md.

Rich message fields

The four read tools marked ‡ accept include_rich_message_fields: true, surfacing everything that lives outside a message's text: attachments, blocks, files, reactions, metadata, plus subtype / bot_id / app_id (bot & app markers) and team (workspace id).

An attachment-only alert looks empty without it:

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

With the flag, the real content appears:

{
  "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's opt-in per call to keep client context lean; for the full developer payload inside metadata, also set include_all_metadata: true.

One caveat: Slack's search API doesn't return rich fields on matches — slack_search_messages finds the hit, then slack_conversations_history or slack_get_thread reads the full content.

Added in 4.4.0 · patch by @rvandam (#143).

How token storage works

Session tokens (xoxc- + xoxd-) come from your browser. The server resolves them through a four-layer fallback, first hit wins:

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 as tokens age out. File writes are atomic (temp → chmod → rename) and concurrent refreshes are mutex-locked, so nothing corrupts and no two writers clobber each other.

Chrome extraction diagnoses itself: every failure names its cause — keychain_timeout, no_slack_cookie_row, cookie_decrypt_failed, and more, per profile — instead of one opaque error. The full failure-code table (and the Keychain timeout tunable) is in docs/TROUBLESHOOTING.md.

How the Chrome extraction works

No DevTools, no "paste this cookie" step — on macOS the server reads what Chrome already has on disk and decrypts it the way Chrome itself does:

• The token (xoxc-) is matched out of Chrome's on-disk LevelDB (Local Storage/leveldb), newest record first. No live Slack tab, no AppleScript, no dev flags — it works even with Chrome closed.
• The cookie (xoxd-) is decrypted with Chrome's own scheme. The server copies the cookie SQLite DB (WAL sidecars included, since Chrome holds a lock on the live file), reads the machine's Chrome Safe Storage key from the Keychain, then runs PBKDF2(key, "saltysalt", 1003, sha1) → AES-128-CBC to turn the v10 blob back into your session cookie.

Same decryption Chrome runs on every launch — the server just does it once, in about a second, so no cookie ever passes through your clipboard. It's readable JavaScript you can audit before trusting it with anything.

Storage backends

On macOS, --setup asks where credentials should live and remembers the answer in ~/.slack-mcp-meta.json; every process — server, CLI, LaunchAgent — follows the same choice. SLACK_MCP_TOKEN_STORAGE overrides it.

One honest trade-off in keychain-only mode: background refresh can't write to a locked Keychain — fresh tokens are held in memory (storage.unpersisted_fresh_tokens) so the session keeps working, and the next cycle retries. An unrecognized mode fails the server at startup rather than quietly downgrading to plaintext, and all token-file and metadata writes are serialized across processes with a lock file.

When tokens expire (every week or two)

Slack rotates session tokens roughly every 1–2 weeks. When they die, the server catches it — invalid_auth, not_authed, token_expired, token_revoked, account_inactive, or a bare HTTP 401 — and hands back a recovery message at the moment of pain instead of a raw Slack error.

Fix it yourself — re-extract fresh tokens:

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

On macOS with a logged-in Slack tab open in Chrome, call the slack_refresh_tokens tool (or npm run tokens:auto) without leaving your editor. To survive long idle stretches, wire up the optional token-refresh LaunchAgent.

Never rotate again — the hosted version uses OAuth, which doesn't die on the 1–2-week clock. Free tier, no card.

The recovery message shows at most once per process per hour; repeat failures inside that window get a one-liner so agents in retry loops don't spam. Set SLACK_MCP_NO_UPSELL=1 to drop the hosted line and keep only the self-fix guidance.

Multiple workspaces

Run work and personal Slack side-by-side. Each server instance gets its own credential namespace — token file, Keychain entries, metadata, write lock — so setup or refresh in one never touches the other:

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

Set each one up once: npx -y @jtalk22/slack-mcp --setup --profile work. When the workspaces live in different Chrome profiles, add SLACK_MCP_CHROME_PROFILE so each profile's extraction targets the right browser profile. Invalid profile names fail closed at startup — the same discipline as every other credential setting here.

Hosted (optional — the OSS package is complete without it)

Everything above is free, MIT-licensed, and runs entirely on your machine. The hosted brain at mcp.revasserlabs.com exists for exactly two things the OSS package deliberately doesn't do: AI summarization (smart_search, catch_me_up, triage) and permanent OAuth (no 2-week token rotation). If you don't want either, you never need it. The OSS server is complete; hosted earns its keep when the workflow has to run tomorrow — on a schedule, without a token to babysit.

_{Live pricing: mcp.revasserlabs.com/pricing}

Self-hosted HTTP mode

Prefer to host the HTTP endpoint yourself (Cloudflare Worker, VPS, etc.)? The server ships that transport too:

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 — npx -y @jtalk22/slack-mcp --setup, or slack_refresh_tokens on macOS. Prevent silent expiry with the token-refresh LaunchAgent.
• DMs not showing — call slack_list_conversations with discover_dms=true.
• Client not seeing tools — check the JSON syntax in your config, then fully restart the client (MCP servers snapshot at launch).

More in docs/TROUBLESHOOTING.md.

Security

• Token files are chmod 600 (owner-only).
• macOS Keychain encrypted backup — or exclusive storage via SLACK_MCP_TOKEN_STORAGE=keychain-only (zero plaintext on disk, verified writes, loud structured failures).
• Fail-closed config: an unrecognized storage mode kills the server at startup instead of guessing.
• The web server binds to localhost only; API keys use crypto.randomBytes.
• Full policy: SECURITY.md.

Provenance: don't take my word for it

You're about to hand a package your live Slack cookie. Fair to want proof of what it is. Every release publishes straight from CI with npm provenance: the tarball on npm is signed and traces to this repo's exact commit and GitHub Actions run — no hand-uploaded build in the path. Verify it in one command, before you trust it with anything:

npm audit signatures

A green line means the code you install is the code you can read here. If it ever isn't, that command says so.

Docs

Setup · API Reference · Architecture · Deployment Modes · Use-Case Recipes · Compatibility · Troubleshooting · Roadmap

Contributing

PRs welcome. Run node --check on any file you touch before submitting.

License

MIT — see LICENSE.

Disclaimer

Not affiliated with Slack Technologies, Inc. This server uses browser session credentials — check your workspace's acceptable-use policy before running it.