Slack MCP Server

Session-based Slack MCP for Claude and MCP clients. Local-first stdio/web with secure-default hosted HTTP in v3.

Install + Verify

npx -y @jtalk22/slack-mcp --setup
npx -y @jtalk22/slack-mcp@latest --version
npx -y @jtalk22/slack-mcp@latest --doctor
npx -y @jtalk22/slack-mcp@latest --status

Setup guide · 30-second verify reference · Autoplay demo landing · Latest release · npm package

Motion proof: 20-second mobile clip · Live demo walkthrough · Share card

Hosted migration note: v3.0.0 keeps local stdio/web flows unchanged; hosted /mcp requires SLACK_MCP_HTTP_AUTH_TOKEN and SLACK_MCP_HTTP_ALLOWED_ORIGINS.

Maintainer/operator: jtalk22 (james@revasser.nyc)
Release: v3.0.0 · Notes: v3.0.0 notes · Support: deployment intake

If this saved you setup time, consider starring the repo. Maintenance support: GitHub Sponsors · Ko-fi · Buy Me a Coffee

v3.0.0 at a Glance

Hosted HTTP /mcp now requires bearer auth by default (SLACK_MCP_HTTP_AUTH_TOKEN).
Hosted HTTP CORS now uses explicit allowlisting (SLACK_MCP_HTTP_ALLOWED_ORIGINS).
Local-first paths (stdio, web) stay compatible.
MCP tool names stay stable (no renames/removals).

60-Second Hosted Migration

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

Request with:

Authorization: Bearer <SLACK_MCP_HTTP_AUTH_TOKEN>

Emergency local fallback only:

SLACK_MCP_HTTP_INSECURE=1 node src/server-http.js

For guided hosted rollout requirements, open: deployment intake

Why This Exists

I built this because I was working with someone to help me manage a complex workload, and we kept hitting walls. They needed context from my messages—"what did X say about Y?"—and standard app/OAuth flows were too constrained for that workflow.

Screenshotting messages is not a workflow.

This server bridges the gap. It creates a secure, local bridge between Claude and your Slack web session. It gives your MCP client the same access you already have in the browser—search history, summarize threads, and retrieve prior context—without fighting the platform.

Slack MCP Server Web UI

Architecture: Local Session Mirroring

Instead of authenticating as a bot, this server leverages your existing Chrome session credentials (macOS) or manual token injection (Linux/Windows). It mirrors your user access exactly—if you can see it in Slack, Claude can see it too.

Session Mirroring Flow

Why Not OAuth?

OAuth vs Session Mirroring

Trade-off: Session tokens expire every 1-2 weeks. Auto-refresh (macOS) or manual update keeps things running.

Features

Core Capabilities

Read Any Message - DMs, private channels, public channels
Full Export - Conversations with threads and resolved usernames
Search - Query across your entire workspace
Send Messages - DMs or channels, with thread support
User Directory - List and search 500+ users with pagination

Stability

Auto Token Refresh - Extracts fresh tokens from Chrome automatically (macOS only)
Atomic Writes - File operations use temp-file-then-rename to prevent corruption
Zombie Protection - Background timers use unref() for clean process exit
Race Condition Safety - Mutex locks prevent concurrent token extraction
Rate Limit Handling - Exponential backoff with jitter

Tools

Tool	Description
`slack_health_check`	Verify token validity and workspace info
`slack_token_status`	Detailed token age, health, and cache stats
`slack_refresh_tokens`	Auto-extract fresh tokens from Chrome
`slack_list_conversations`	List DMs/channels (with lazy discovery cache)
`slack_conversations_history`	Get messages from a channel or DM
`slack_get_full_conversation`	Export full history with threads
`slack_search_messages`	Search across workspace
`slack_send_message`	Send a message to any conversation
`slack_get_thread`	Get thread replies
`slack_users_info`	Get user details
`slack_list_users`	List workspace users (paginated, 500+ supported)

Quick Start

Runtime: Node.js 20+

30-Second Compatibility Check

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

Expected:

--setup launches the interactive wizard
--doctor returns one clear next action with exit code:
- 0 ready
- 1 missing credentials
- 2 invalid/expired credentials
- 3 connectivity/runtime issue
--status is read-only and non-mutating

Command reference: HN launch kit

Known Working Clients

Claude Desktop (macOS/Windows/Linux)
Claude Code CLI
Local browser mode (web)
Hosted Node runtime (http)
Cloudflare Worker / Smithery transport

Compatibility matrix: compatibility matrix

Option A: npm (Recommended)

npm install -g @jtalk22/slack-mcp

Option B: Clone Repository

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

Option C: Docker

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

Install Sanity (Clean Temp Directory)

tmpdir="$(mktemp -d)"
cd "$tmpdir"
npx -y @jtalk22/slack-mcp --version
npx -y @jtalk22/slack-mcp --help
npx -y @jtalk22/slack-mcp --status

Expected:

--version and --help exit 0
--status exits non-zero until credentials are configured
--status is read-only and never attempts Chrome extraction

Configuration

Step 1: Get Your Tokens

Setup Wizard (Recommended)

The interactive setup wizard handles token extraction and validation automatically:

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

macOS: Auto-extracts tokens from Chrome (have Slack open in a tab)
Linux/Windows: Guides you through manual extraction step-by-step
Validates tokens against Slack API before saving
Stores tokens securely at ~/.slack-mcp-tokens.json

Check Token Status

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

Alternative: Manual Token Scripts

# macOS auto-extraction
npm run tokens:auto

# Manual entry (all platforms)
npm run tokens:refresh

# Check health
npm run tokens:status

Step 2: Configure Claude

Claude Desktop (macOS)

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

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

Claude Desktop (Windows)

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

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

Claude Code (CLI)

Add to ~/.claude.json:

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

Claude Code reads tokens from ~/.slack-mcp-tokens.json automatically.

Docker Configuration

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

Step 3: Restart Claude

Fully quit and reopen Claude. The Slack tools will appear.

Architecture

Token Persistence (4 Layers)

Priority 1: Environment Variables (SLACK_TOKEN, SLACK_COOKIE)
    ↓ fallback
Priority 2: Token File (~/.slack-mcp-tokens.json)
    ↓ fallback
Priority 3: macOS Keychain (encrypted)
    ↓ fallback
Priority 4: Chrome Auto-Extraction (macOS only)

Stability Features

Atomic Writes

All file operations (tokens, DM cache) use atomic writes:

Write to temp file → chmod 600 → rename to target

This prevents JSON corruption if the process is killed mid-write.

Zombie Process Protection

Background refresh timers use unref():

const timer = setInterval(refreshTokens, 4 * 60 * 60 * 1000);
timer.unref(); // Process can exit even if timer is pending

When Claude closes the MCP connection, the server exits cleanly.

Race Condition Prevention

A mutex lock prevents concurrent Chrome extractions:

if (refreshInProgress) return null; // Skip if already refreshing
refreshInProgress = true;
try { return extractFromChromeInternal(); }
finally { refreshInProgress = false; }

Web UI (optional browser/local fallback)

Claude now supports remote MCP connectors on paid plans. For claude.ai, the preferred path is adding a remote connector in Settings -> Connectors.

Reference:

Use this Web UI when you want a local localhost dashboard, REST access, or a fallback workflow without remote connector hosting:

npm run web
# Or: npx -y @jtalk22/slack-mcp web

Magic Link: The console prints a one-click URL with the API key embedded:

════════════════════════════════════════════════════════════
  Slack Web API Server v3.0.0
════════════════════════════════════════════════════════════

  Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx

Just click the link - no copy-paste needed. The key is saved to your browser and stripped from the URL for security.

DMs View	Channels View

Hosted HTTP Mode (Secure Defaults)

Use this mode only when you need a remote MCP endpoint:

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

Behavior:

/mcp requires Authorization: Bearer <SLACK_MCP_HTTP_AUTH_TOKEN> by default.
Cross-origin browser calls are denied unless origin is listed in SLACK_MCP_HTTP_ALLOWED_ORIGINS.
For local testing only, you can opt out with SLACK_MCP_HTTP_INSECURE=1.

Operations Guides

Docs Index - One-click index for setup, API, troubleshooting, deployment, and support docs
Deployment Modes - Choose the right operating model (stdio, web, hosted HTTP, Smithery/Worker)
Use Case Recipes - 12 copy/paste prompts mapped to current tool contracts
Support Boundaries - Scope, response targets, and solo-maintainer capacity limits
Release Health - Track setup reliability and support-load targets through this release cycle

If you're evaluating team rollout, start with Deployment Modes before exposing remote endpoints.

Getting Help Fast

Run:

npx -y @jtalk22/slack-mcp --version
npx -y @jtalk22/slack-mcp --doctor

If setup fails, run:
```
npx -y @jtalk22/slack-mcp --setup
```
Open an issue with full environment details:
- Bug Report Template
- Deployment Intake Template
For guided hosted rollout support:
- GitHub Discussions
Check scope and response targets:
- Support Boundaries
- Troubleshooting Guide

Troubleshooting

Tokens Expired

# macOS: Auto-refresh from Chrome
slack_refresh_tokens  # In Claude
# Or: npm run tokens:auto

# Package setup wizard
npx -y @jtalk22/slack-mcp --setup

# Linux/Windows: Manual update
# Edit ~/.slack-mcp-tokens.json with fresh values

DMs Not Showing

Use discover_dms: true to force discovery:

slack_list_conversations with discover_dms=true

This caches DM channel IDs for 24 hours.

Chrome Extraction Fails

Chrome must be running (not minimized to Dock)
Slack tab must be open at app.slack.com
You must be logged in
In Chrome menu, enable View > Developer > Allow JavaScript from Apple Events

Claude Desktop Not Seeing Tools

Verify JSON syntax in config file
Check logs: ~/Library/Logs/Claude/mcp*.log
Fully restart Claude (Cmd+Q, then reopen)

Project Structure

slack-mcp-server/
├── src/
│   ├── server.js         # MCP server (stdio transport)
│   └── web-server.js     # REST API + Web UI
├── lib/
│   ├── token-store.js    # 4-layer persistence + atomic writes
│   ├── slack-client.js   # API client, LRU cache, retry logic
│   ├── tools.js          # MCP tool definitions
│   └── handlers.js       # Tool implementations
├── public/
│   ├── index.html        # Web UI
│   └── demo.html         # Interactive demo
└── scripts/
    └── token-cli.js      # Token management CLI

Security

Token files stored with chmod 600 (owner-only)
macOS Keychain provides encrypted backup
Web server binds to localhost only
Never commit tokens to version control
API keys are cryptographically random (crypto.randomBytes)

Platform Support

Feature	macOS	Linux	Windows
MCP Server	Yes	Yes	Yes
Token File	Yes	Yes	Yes
Auto-Refresh from Chrome	Yes	No	No
Keychain Storage	Yes	No	No
Web UI	Yes	Yes	Yes

Contributing

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

If this project saves you setup time, consider starring the repository.

License

MIT - See LICENSE

Disclaimer

This project uses unofficial Slack APIs. Use at your own risk. Not affiliated with or endorsed by Slack Technologies.

Slack MCP Server

Slack MCP Server

Install + Verify

v3.0.0 at a Glance

60-Second Hosted Migration

Why This Exists

Architecture: Local Session Mirroring

Why Not OAuth?

Features

Core Capabilities

Stability

Tools

Quick Start

30-Second Compatibility Check

Known Working Clients

Option A: npm (Recommended)

Option B: Clone Repository

Option C: Docker

Install Sanity (Clean Temp Directory)

Configuration

Step 1: Get Your Tokens

Setup Wizard (Recommended)

Check Token Status

Alternative: Manual Token Scripts

Step 2: Configure Claude

Claude Desktop (macOS)

Claude Desktop (Windows)

Claude Code (CLI)

Docker Configuration

Step 3: Restart Claude

Architecture

Token Persistence (4 Layers)

Stability Features

Atomic Writes

Zombie Process Protection

Race Condition Prevention

Web UI (optional browser/local fallback)

Hosted HTTP Mode (Secure Defaults)

Operations Guides

Getting Help Fast

Troubleshooting

Tokens Expired

DMs Not Showing

Chrome Extraction Fails

Claude Desktop Not Seeing Tools

Project Structure

Security

Platform Support

Contributing

License

Disclaimer

Related Servers

Email

Gmail

Google Meet MCP Server

Slack MCP Server

LinkedIn MCP Server

Windows Notification Server

Twitter NoAuth

Slack Webhook

WhatsApp

KickMCP