# slack-mcp-claude-auth

Local stdio MCP proxy for the official Slack MCP endpoint.

Intended to be used with the [Pi Coding Agent](https://pi.dev) and the [pi-mcp-adapter](https://github.com/nicobailon/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

```bash
npm install
npm run build
```

## Pi MCP config

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

```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:

```text
/reload
/mcp reconnect slack
```

If direct tools are disabled, use proxy:

```ts
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:

```text
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:

```bash
SLACK_MCP_WRITEBACK=0
```

## Common failure

```text
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` |