slack-mcp-server

Slack MCP Server

Slack MCP Server

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

Slack MCP tools in action

npm Build Status License: MIT

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:

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.

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

Stability

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:

Command reference: docs/HN-LAUNCH.md

Known Working Clients

Compatibility matrix: docs/COMPATIBILITY.md

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:

Configuration

Step 1: Get Your Tokens

The interactive setup wizard handles token extraction and validation automatically:

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

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 | |----------|---------------| | ![DMs](/slack-mcp-server/docs/images/demo-main.png) | ![Channels](/slack-mcp-server/docs/images/demo-channels.png) |

Operations Guides

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

Getting Help Fast

  1. Run: 
    npx -y @jtalk22/slack-mcp --version
npx -y @jtalk22/slack-mcp --doctor
  2. If setup fails, run: 
    npx -y @jtalk22/slack-mcp --setup
  3. Open an issue with full environment details:
  4. Check scope and response targets:

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

Claude Desktop Not Seeing Tools

  1. Verify JSON syntax in config file
  2. Check logs: ~/Library/Logs/Claude/mcp*.log
  3. 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

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.

This site is open source. Improve this page.