Slack MCP Server

Session-based Slack access for Claude using your existing workspace permissions.

30-Second Proof

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

Expected:

--version prints 2.0.0
--doctor exits with 0|1|2|3
--status is read-only and non-mutating

v2.0.0 is live with deterministic diagnostics and stable tool contracts.
Release notes: .github/v2.0.0-release-notes.md
Maintainer/operator: jtalk22 (james@revasser.nyc)

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.

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.

Why Not OAuth?

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`	New: 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 --version
npx -y @jtalk22/slack-mcp --doctor
npx -y @jtalk22/slack-mcp --setup

Expected:

--version prints slack-mcp-server v2.0.x
--doctor returns one clear next action with exit code:
- 0 ready
- 1 missing credentials
- 2 invalid/expired credentials
- 3 connectivity/runtime issue
--setup launches the interactive wizard

Command reference: docs/HN-LAUNCH.md

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: docs/COMPATIBILITY.md

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 v2.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.

Screenshots

DMs View	Channels View

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
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 you find this project useful, consider starring the repo.

License

MIT - See LICENSE

Disclaimer

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

Name		Name	Last commit message	Last commit date
Latest commit History 129 Commits
.githooks		.githooks
.github		.github
docs		docs
lib		lib
public		public
scripts		scripts
src		src
workers		workers
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
glama.json		glama.json
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
smithery.yaml		smithery.yaml

License

jtalk22/slack-mcp-server

Folders and files

Latest commit

History

Repository files navigation

Slack MCP Server

30-Second Proof

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)

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

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Uh oh!

Contributors 4

Languages

Packages