slack-readonly-mcp

A self-hosted, read-only Slack MCP server for Claude Code (and any MCP client).

Why this exists

Hosted Slack MCP connectors route your Slack message content through a third-party hosted MCP layer. If you care about where that data goes, that hop sits outside your control. This server avoids it:

• It runs locally as a stdio subprocess that the MCP client launches.
• It calls the Slack Web API directly with your own token.
• Tool results flow only into your MCP client's context → whatever model endpoint you've configured (e.g. an org with zero data retention).

So the full path is: your machine → Slack API → your MCP client → your model endpoint. No third-party MCP intermediary. Data-retention guarantees are a property of the model endpoint you point the client at — this server doesn't change them, it only adds tools.

Note: Data that lives in Slack is governed by your Slack plan, not by this server. This server only governs the path between Slack and your client.

Tools (all read-only)

Tool	Purpose
slack_list_channels	List channels (id, name, topic, members)
slack_channel_history	Recent messages in a channel
slack_thread_replies	All replies in a thread
slack_conversations_info	Metadata for one channel
slack_user_info	Look up a user (email omitted)
slack_list_users	List workspace users (email omitted)
slack_search_messages	Search messages — requires a user token (see below)

Setup

1. Create a Slack app with read-only scopes

At https://api.slack.com/apps → Create New App → From a manifest, paste:

display_information:
  name: Claude Read-Only
oauth_config:
  scopes:
    bot:
      - channels:read
      - channels:history
      - groups:read
      - groups:history
      - im:read
      - im:history
      - mpim:read
      - mpim:history
      - users:read
    user:
      - search:read   # optional — only needed for slack_search_messages
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false

Install it to the workspace, then copy the Bot User OAuth Token (xoxb-…). If you want search, also copy the User OAuth Token (xoxp-…). Invite the bot to any private channels you want it to read (/invite @Claude Read-Only).

2. Build

npm install
npm run build

3. Register with Claude Code

claude mcp add slack-readonly \
  --env SLACK_BOT_TOKEN=xoxb-your-token \
  -- node /path/to/slack-readonly-mcp/dist/index.js

Or, for a project-scoped .mcp.json (keep the token in your shell env, not in the file — Claude Code expands ${VAR}):

{
  "mcpServers": {
    "slack-readonly": {
      "command": "node",
      "args": ["/path/to/slack-readonly-mcp/dist/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_USER_TOKEN": "${SLACK_USER_TOKEN}"
      }
    }
  }
}

Search caveat

Slack's search.messages endpoint cannot be called with a bot token — it requires a user token. Set SLACK_USER_TOKEN (xoxp-…, search:read) to enable slack_search_messages; without it, the other six tools work and search returns a clear error.

Notes

• All logging goes to stderr; stdout is the JSON-RPC channel.
• The server fails fast (exit 1) if SLACK_BOT_TOKEN is unset.
• Read-only by design. Adding write tools (post/reply/react) means adding write scopes — a deliberately separate, larger-blast-radius change.

License

MIT