Slack Web API

Quick Start

1. Create a Slack App

1. Go to api.slack.com/apps > Create New App > From a manifest
2. Paste the contents of manifest.json
3. Install to your workspace
4. Copy the User OAuth Token (xoxp-...) from OAuth & Permissions

2. Add to your AI client

claude mcp add slack -- uvx --from git+https://github.com/karbassi/slack-mcp.git slack-mcp

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
      "env": {
        "SLACK_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
      "env": {
        "SLACK_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
      "env": {
        "SLACK_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "slack": {
        "command": "uvx",
        "args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
        "env": {
          "SLACK_XOXP_TOKEN": "xoxp-..."
        }
      }
    }
  }
}

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/slack-mcp", "slack-mcp"]
    }
  }
}

SLACK_MCP_TRANSPORT=http SLACK_MCP_PORT=8501 slack-mcp

{
  "mcpServers": {
    "slack": { "type": "http", "url": "http://127.0.0.1:8501/mcp" }
  }
}

What Can It Do?

"Catch me up on #engineering from today" "Reply to Sarah's thread saying we'll ship it Monday" "Search for anything about the Q3 roadmap" "Create a channel called #project-atlas and invite the design team"

Plus resolve_names (bulk ID→name resolution) and cache_clear (bust the response cache on demand) utility tools.

Beyond the Official API

68 undocumented and legacy endpoints — the same internal APIs that Slack's own apps use. Requires session tokens (xoxc+xoxd).

Authentication

[!TIP] The xoxp token covers all Slack Web API tools. Utility tools like resolve_names and cache_clear work without additional auth. For undocumented endpoints (unread counts, workspace boot, file editing), you also need xoxc+xoxd — grab them from your browser cookies while logged into slack.com.

Caching

Responses are cached automatically to reduce API calls:

• Stable data (users, teams, bots, emoji) — 1 hour TTL
• Dynamic data (channel lists, members, bookmarks) — 5 minute TTL
• Old threads (conversations_replies with ts > 1 hour old) — 1 hour TTL
• Bounded history (conversations_history with old date range) — 1 hour TTL
• Resolved names (user/bot → 1 hour, channel → 5 minutes)

Cache is stored at the platform-native location (~/Library/Caches/slack-mcp on macOS, ~/.cache/slack-mcp on Linux). Set XDG_CACHE_HOME to override.

Use the cache_clear tool to bust the cache when you need fresh data.

Name Resolution

All tool responses automatically resolve user, channel, DM, and bot IDs to display names via a resolved_names field — no extra tool calls needed. Resolved names are disk-cached to avoid redundant API lookups.

Response Compaction

15 high-volume tools automatically strip bloat from Slack API responses — blocks (duplicates text), attachments (link unfurls), thumbnails (22 per file), and metadata noise. Measured reductions:

Compaction is on by default. Pass detailed=True to any compactable tool to get the full Slack API response.

Development

git clone https://github.com/karbassi/slack-mcp.git
cd slack-mcp
uv sync
uv run pre-commit install            # ruff + ty on every commit
mise run check                       # test + lint + security scan
mise run test:integration            # requires tokens in .env

[!NOTE] ~68 integration tests are skipped because they require a bot token (xoxb), Slack Connect, interactive triggers (e.g. views.open), or would be destructive (e.g. auth.revoke). Adding bot token support is a future goal.

License

MIT