Slack

Slack MCP

MCP server that gives AI agents access to your Slack workspaces using session tokens. No OAuth apps, no bot permissions, no admin approval required.

Beyond reading and writing messages, it accumulates a durable picture of the workspace — every channel and user's state over time, departures kept as dated tombstones — and synthesizes a relationship graph from it on demand: estate view='about' person='X' answers "tell me about X" with their footprint, circle, and a ranked reading plan. The graph is never maintained as a store; it is computed per query from two small local ledgers that hold no message content (design note). Add render='graph' to draw one view as a static HTML page you open locally.

How it works

Slack MCP uses your existing browser session tokens (xoxc/xoxd) to interact with Slack on your behalf. It reads stealthily by default — only the mark-read tool triggers read receipts. Everything else is invisible to other users.

Token extraction is built into the binary. If you're logged into Slack in Chrome or Firefox, the setup flow can extract tokens automatically — no copy-pasting from DevTools.

Prerequisites

You need an active Slack session in your browser. Log into your workspace at app.slack.com in Chrome, Chromium, Edge, or Firefox before running setup.

Install

Claude Code

claude mcp add slack-mcp -- npx -y @aaronsb/slack-mcp

Then ask Claude to run the auth tool. It will guide you through browser selection, profile selection, and automatic token extraction.

Claude Desktop

Download the .mcpb file for your platform from the latest release:

Open the file (double-click or drag into Claude Desktop). When prompted for tokens, you can either:

• Leave them blank and use the auth tool after connecting
• Paste tokens if you already have them

Standalone binary

Download the binary for your platform from releases, then:

# Extract tokens from your browser (interactive)

./slack-mcp setup

Run as MCP server (stdio, default)

./slack-mcp

Run as MCP server (SSE, for remote/shared access)

./slack-mcp --transport sse

npm (global)

npm install -g @aaronsb/slack-mcp

slack-mcp setup

Token setup

There are three ways to get your Slack tokens, from easiest to most manual:

Automatic (Chrome/Edge)

The auth MCP tool or slack-mcp setup CLI command will:

1. Detect your installed browsers
2. Let you pick which browser and profile has Slack
3. Open the browser, navigate to Slack, and extract tokens via Chrome DevTools Protocol
4. Validate and save them

Requires Chrome to be fully closed before extraction — your tabs will restore when you reopen it.

Semi-automatic (Firefox)

The setup flow writes a temporary browser extension to a temp directory, then guides you to load it in Firefox via about:debugging. The extension extracts tokens and sends them to the local callback server. It's removed automatically when Firefox closes.

Manual

Run slack-mcp setup or use the auth tool — if no browser is detected or automatic extraction fails, it falls back to a localhost web page with step-by-step DevTools instructions.

You can also set tokens directly via environment variables:

export SLACK_MCP_XOXC_TOKEN="xoxc-..."

export SLACK_MCP_XOXD_TOKEN="xoxd-..." ./slack-mcp

Settings come from the environment your MCP client config provides. A .env file in the working directory may set only SLACK_MCP_PERSONALITY and SLACK_MCP_NO_BROWSER, and never overrides a variable the environment already sets. If .env sets any other key the environment does not, the server refuses to start and names the key; set it in the client config instead.

Lifecycle

Over stdio the server exits cleanly when its client is gone: stdin closes, a termination signal arrives (SIGTERM, SIGINT, SIGHUP), or its parent process exits. Each exit flushes the caches and releases the ledger locks, so the next instance is not left read-only. On Windows, the npm wrapper's child.kill terminates the server forcibly, so this graceful shutdown does not run there.

Remote deployment (experimental)

Remote deployment is experimental and has not been tested against a real SSH session. Whether the server supports remote use at all, and in what form, is still open (see #102). Nothing below applies unless you set SLACK_MCP_DEPLOYMENT=remote.

A wedged connection, such as a half-open SSH session, leaves the pipe open with nobody reading it. Only an idle timeout catches that, and it is valid only where it can happen, so the server ties the timeout to how it is deployed:

The deployment is local unless you declare it. The server does not detect it: SSH_CONNECTION only means some ancestor logged in over SSH (running claude in an SSH session, VS Code Remote-SSH), not that the MCP pipe crosses SSH. Only the MCP client config that launches the server knows, so declare remote there, in the entry that starts the server over SSH. ssh does not forward your environment, so pass the variable through the remote command line with env:

{

"mcpServers": { "slack": { "command": "ssh", "args": ["host", "env", "SLACK_MCP_DEPLOYMENT=remote", "slack-mcp"] } } }

(ssh joins the arguments into one remote command line, so this runs env SLACK_MCP_DEPLOYMENT=remote slack-mcp on the host. Setting it in the client's env block does not work, because that only reaches the local ssh process.) A timeout set where it is not allowed, or a value that does not parse, stops the server at startup with the reason on stderr.

Tools

Verb encodes effect, noun encodes domain, parameter encodes scope (ADR-009); the batch executor encodes composition, never effect, and admits only the read nouns (ADR-010). Every noun echoes its effective parameters and pages every capped list.

Outbound safety

Everything this server posts is attributed to your account, and the agent reads text anyone in the workspace can write. So every say passes a fixed order before any content reaches Slack or any DM is opened (ADR-013):

1. Strike lock — after too many blocks, every say and mark-read is refused until you clear it (CLI, or the unlock page).
2. Exchange directory — file names are bare names inside it (ADR-012).
3. Quarantine — a destination a block closed refuses say and mark-read; reads keep working.
4. Secret scanner — the text as sent, a reaction's emoji, and each file's name and bytes, including base64, hex, URL-encoded, gzip, and zlib content. A match is a block: nothing is sent, and the agent is told the class and the field, never the value.
5. Approval gate — a destination outside your organization, or (in strict) a file download took from another conversation, waits for you as a pending request. Nothing is sent until you approve it.

Two settings in your MCP client config shape this (ADR-014); .env cannot set them:

A block posts the notice into the quarantined conversation, never to a destination outside your organization and never to a person with no DM. Blocks, pending requests, and sends trust let through are logged as outbound-safety: BLOCKED, PENDING, and TRUSTED lines (destination, IDs, class, counts; never content). When state needs you, inbox, messages, estate, and batch results open with a banner.

A block that cannot be written to the quarantine file holds every say and mark-read in that server process (in memory) and issues a lift request (lift=strikes). Fix the file, then approve the request or run