slack-mcp-claude-auth

Local stdio MCP proxy for the official Slack MCP endpoint.

Intended to be used with the Pi Coding Agent and the pi-mcp-adapter extension installed. Only for MacOS. It uses Claude's official Slack plugin for authorisation flow so one doesn't need to create its own Slack application with its own client ID.

At first launch and if refresh token is expired, an authorisation to the officila Slack plugin is needed via the Claude CLI. No Slack tokens are stored or shared anywhere. If token is refreshed, it's stored into the same keychain record like it would be done via official Claude's Slack plugin.

Build

npm install
npm run build

Pi MCP config

Add to ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["/Users/k.babaev/Sources/_index-only/slack-mcp-claude-auth/dist/index.js"],
      "lifecycle": "lazy"
    }
  }
}

Then reload Pi and refresh metadata:

/reload
/mcp reconnect slack

If direct tools are disabled, use proxy:

mcp({ server: "slack" })
mcp({ search: "slack thread" })
mcp({ tool: "slack_read_thread", args: "{...}" })

Dynamic tool list

The wrapper implements MCP tools/list by calling official Slack MCP tools/list. Tool schemas, descriptions, and names come from Slack, not from this repo.

Tool list cache:

• default TTL: 24 hours (SLACK_MCP_TOOL_LIST_CACHE_MS=86400000)
• default path: ~/.cache/slack-mcp-claude-auth/tools.json
• cache contains only tool metadata, no Slack tokens
• expired cache is used as fallback if refresh fails
• set SLACK_MCP_TOOL_LIST_CACHE_MS=0 to disable wrapper cache

Tool names:

• official Slack tools are named slack_search_users, slack_read_thread, etc.
• pi-mcp-adapter also prefixes tools with server name slack_
• wrapper strips the official redundant slack_ prefix before exposing tools, so Pi names become slack_search_users, not slack_slack_search_users
• disable with SLACK_MCP_STRIP_REDUNDANT_TOOL_PREFIX=0

If pi-mcp-adapter direct tools are enabled, adapter may also cache metadata; run /mcp reconnect slack and /reload after Slack changes tools or after changing prefix behavior.

Claude Code auth source

Credentials are read from macOS Keychain item:

• service: Claude Code-credentials
• JSON path: mcpOAuth["plugin:slack:slack|38801a7d845718b3"]

Defaults match current Claude Code Slack MCP auth:

SLACK_MCP_CLIENT_ID=1601185624273.8899143856786
SLACK_MCP_CLAUDE_CRED_KEY=plugin:slack:slack|38801a7d845718b3
SLACK_MCP_URL=https://mcp.slack.com/mcp

On token refresh, wrapper writes refreshed access/refresh token back into the same Claude Code keychain JSON by default. Disable with:

SLACK_MCP_WRITEBACK=0

Common failure

Slack token refresh HTTP 400: invalid_grant

Claude Code keychain refresh token is stale/invalid. Re-authorize Slack in Claude Code CLI, then retry /mcp reconnect slack in Pi.

Environment knobs

Variable	Default
SLACK_MCP_URL	https://mcp.slack.com/mcp
SLACK_TOKEN_ENDPOINT	https://slack.com/api/oauth.v2.user.access
SLACK_MCP_CLIENT_ID	Claude Code Slack client id
SLACK_MCP_CLAUDE_CRED_KEY	Claude Code Slack MCP credential key
SLACK_MCP_KEYCHAIN_SERVICE	Claude Code-credentials
SLACK_MCP_KEYCHAIN_ACCOUNT	current macOS username
SLACK_MCP_REFRESH_BUFFER_MS	300000
SLACK_MCP_SESSION_TTL_MS	79200000
SLACK_MCP_TOOL_LIST_CACHE_MS	86400000
SLACK_MCP_TOOL_LIST_CACHE_PATH	~/.cache/slack-mcp-claude-auth/tools.json
SLACK_MCP_STRIP_REDUNDANT_TOOL_PREFIX	1
SLACK_MCP_WRITEBACK	1