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

Tool	Description
slack_list_workspaces	List configured workspaces and which is default
slack_list_channels	Browse channels, DMs, groups — filter by type or name
slack_read_messages	Read recent messages from any channel or DM
slack_read_thread	Read all replies in a thread
slack_send_message	Send a message as you
slack_reply_thread	Reply in a thread as you
slack_search	Search messages with Slack operators (from:, in:, before:, etc.)
slack_list_users	List or search workspace members
slack_set_status	Set your status emoji and text
slack_react	Add a reaction to a message

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.

Scope	Purpose
channels:history	Read messages in public channels
channels:read	List public channels
groups:history	Read messages in private channels
groups:read	List private channels
im:history	Read direct messages
im:read	List direct messages
mpim:history	Read group DMs
mpim:read	List group DMs
chat:write	Send messages as you
users:read	List workspace members
users:read.email	See member emails
search:read	Search messages
users.profile:write	Set your status
reactions:write	Add reactions
reactions:read	Read reactions

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