nomos-slack-mcp

An MCP server that lets AI agents read and write Slack messages as you — not as a bot. Messages, reactions, and status updates appear exactly as if you typed them yourself.

Built for Claude Code and any MCP-compatible client. Supports multiple Slack workspaces with independent authentication.

Why?

Existing Slack integrations send messages as a bot with an APP badge. This uses Slack user tokens (xoxp-) so your agent operates as you — indistinguishable from you being at the keyboard.

Features

• Send as you — no bot badge, no "APP" indicator
• Multi-workspace — manage 2+ Slack workspaces with separate tokens and permissions
• 10 tools — read, write, search, react, set status
• Smart resolution — use #channel-name, @username, or raw channel IDs
• Local only — tokens stay on your machine at ~/.nomos/slack/config.json with 0600 permissions

Quick Start

1. Create a Slack App

For each workspace you want to connect:

1. Go to api.slack.com/apps → Create New App → From app manifest
2. Paste the contents of slack-app-manifest.yml (or use the JSON version)
3. Click Create
4. Go to Install App → Install to Workspace → Allow

[!TIP] The manifest pre-configures all required User Token Scopes and the OAuth redirect URL. No manual scope configuration needed.

2. Install

git clone https://github.com/project-nomos/nomos-slack-mcp.git
cd nomos-slack-mcp
pnpm install
pnpm build

3. Add Your Workspaces

Option A: OAuth flow (recommended)

pnpm add-workspace

You'll be prompted for:

• A workspace alias (e.g. work, side-project)
• Your Slack App's Client ID and Client Secret (found under Basic Information in your Slack App settings)

The script opens your browser for OAuth authorization and stores the user token automatically.

Option B: Manual token

pnpm add-workspace -- --manual

Paste your xoxp- token directly. Find it in your Slack App under OAuth & Permissions → User OAuth Token.

Repeat for each workspace.

4. Connect to Claude Code

claude mcp add nomos-slack -- node /path/to/nomos-slack-mcp/dist/src/index.js

Or add to your MCP config manually:

{
  "mcpServers": {
    "nomos-slack": {
      "command": "node",
      "args": ["/path/to/nomos-slack-mcp/dist/src/index.js"]
    }
  }
}

Tools

Channel Resolution

All tools that accept a channel parameter understand:

• #general — public/private channel by name
• @john — opens a DM with that user
• C0123ABCDEF — raw Slack channel ID

Multi-Workspace

Every tool accepts an optional workspace parameter. Omit it to use your default workspace.

"Read my DMs in the side-project workspace"
→ slack_read_messages({ workspace: "side-project", channel: "@alice" })

Configuration

Config is stored at ~/.nomos/slack/config.json:

{
  "workspaces": {
    "work": {
      "token": "xoxp-...",
      "teamId": "T01ABC123",
      "teamName": "Acme Corp",
      "userId": "U01XYZ789",
      "addedAt": "2026-03-26T10:00:00Z"
    },
    "side-project": {
      "token": "xoxp-...",
      "teamId": "T02DEF456",
      "teamName": "Side Project",
      "userId": "U02UVW012",
      "addedAt": "2026-03-26T11:00:00Z"
    }
  },
  "defaultWorkspace": "work"
}

File permissions are set to 0600 (owner read/write only).

Required Slack Scopes

All scopes are User Token Scopes (not Bot Token Scopes). The included app manifest configures these automatically.

Development

# Install dependencies
npm install

# Build
npm run build

# Type-check without emitting
pnpm check

# Watch mode
pnpm dev

Project Structure

src/
├── index.ts                 # MCP server entry point (stdio transport)
├── config/
│   ├── config-manager.ts    # Read/write ~/.nomos/slack/config.json
│   └── types.ts             # TypeScript interfaces
├── slack/
│   ├── client-manager.ts    # Per-workspace WebClient instances + channel/user resolution
│   └── formatters.ts        # Format Slack API responses for LLM consumption
├── tools/
│   ├── index.ts             # Tool registry
│   ├── list-workspaces.ts
│   ├── list-channels.ts
│   ├── read-messages.ts
│   ├── read-thread.ts
│   ├── send-message.ts
│   ├── reply-thread.ts
│   ├── search.ts
│   ├── list-users.ts
│   ├── set-status.ts
│   └── react.ts
├── oauth/
│   ├── flow.ts              # OAuth 2.0 token exchange
│   └── server.ts            # Local callback server for OAuth
scripts/
└── add-workspace.ts         # CLI for adding workspaces

Security

• Tokens are stored locally at ~/.nomos/slack/config.json with 0600 file permissions
• User tokens (`xoxp-`) are sensitive — they can act as you. Treat them like passwords
• No data leaves your machine except Slack API calls and whatever you send to your LLM provider as context
• Bot tokens are rejected — the config manager validates that tokens start with xoxp-

Troubleshooting

"No workspaces configured" Run pnpm add-workspace to add a workspace.

"Token must be a user token (xoxp-...)" You're using a bot token (xoxb-). Go to your Slack App → OAuth & Permissions → copy the User OAuth Token, not the Bot User OAuth Token.

"Channel #foo not found" The user token can only see channels you've joined. Join the channel in Slack first.

"missing_scope" errors Your Slack App is missing required scopes. Re-create the app using the provided manifest or manually add the missing scope under OAuth & Permissions → User Token Scopes, then reinstall the app.

Rate limiting The Slack SDK handles 429 responses with automatic retry. If you hit persistent rate limits, reduce the frequency of requests. History endpoints are Tier 2 (~20 req/min), most others are Tier 3 (~50 req/min).

License

MIT