MCP Slack Server

A Model Context Protocol (MCP) server for Slack. v4.0.3 loads a single account from environment variables — no encrypted credential store, no keychain, no runtime account switching. To use a second workspace, add a second MCP server entry with its own token (see below).

Features

• 🔑 Env-first auth: One Slack account per server, loaded from SLACK_BOT_TOKEN at startup — no on-disk credentials
• 🧩 Multi-workspace via config: Run one server entry per workspace (e.g. slack, slack-work)
• 🔍 Comprehensive Slack Tools: 40+ tools for messages, channels, users, files, and more
• 📸 File Upload & Diagrams: Upload files; render HTML/Mermaid diagrams as PNGs (diagram rendering needs a one-time npm install puppeteer — no browser is bundled; see slack_send_diagram)
• 🤝 Legate coordination: slack_poll / slack_claim_lane / slack_checkin for multi-session agents
• ✨ Automatic Markdown Conversion: Converts common markdown formatting to Slack's mrkdwn format

Installation & Configuration

The server reads its token from the env block of its MCP server entry. Add an entry to your Claude config (~/.claude.json or a project-local .mcp.json):

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@chinchillaenterprises/mcp-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-YOUR-BOT-TOKEN",
        "SLACK_USER_TOKEN": "xoxp-YOUR-USER-TOKEN"   // optional
      }
    }
  }
}

Multiple workspaces = multiple server entries

There is no in-app account switching. To talk to a second workspace, add a second server entry with its own token. Tools are namespaced by entry, so they stay separate:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@chinchillaenterprises/mcp-slack"],
      "env": { "SLACK_BOT_TOKEN": "xoxb-PERSONAL-WORKSPACE-TOKEN" }
    },
    "slack-work": {
      "command": "npx",
      "args": ["-y", "@chinchillaenterprises/mcp-slack"],
      "env": { "SLACK_BOT_TOKEN": "xoxb-WORK-WORKSPACE-TOKEN" }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SLACK_BOT_TOKEN | yes | Slack bot token (xoxb-…). Falls back to DEFAULT_BOT_TOKEN for back-compat. | | SLACK_USER_TOKEN | no | Slack user token (xoxp-…) for user-scoped operations. Falls back to DEFAULT_USER_TOKEN. | | SLACK_TEAM_ID | no | Team/workspace ID. Auto-discovered via auth.test on first use if omitted. Falls back to DEFAULT_TEAM_ID. | | SLACK_WORKSPACE | no | Display name for the workspace. Falls back to DEFAULT_ACCOUNT_NAME. |

If SLACK_BOT_TOKEN (or DEFAULT_BOT_TOKEN) is absent, the server still boots — but every tool call returns a clear error telling you to set SLACK_BOT_TOKEN.

Usage

Account Tools (read-only)

• get_active_account: Show which workspace this server is wired to (name, team ID — no secrets)
• list_accounts: List the single active account (kept for back-compat)

Core Slack Tools

Messaging

• slack_send_message: Send messages to channels (with automatic markdown → Slack formatting)
• slack_send_formatted_message: Send rich Block Kit messages
• slack_send_card: Post a polished Block Kit card (header, section blocks with two-column fields, context footer, optional color bar)
• slack_send_table: Post a column-aligned ASCII table inside a code block (lightweight text alternative to slack_send_diagram)
• slack_edit_message: Edit existing messages
• slack_delete_message: Delete messages
• slack_schedule_message: Schedule messages for later
• slack_forward_message: Forward messages between channels

Task Lifecycle (threaded, single-thread progress)

• slack_start_task: Post a parent ⏳ <title> card (adds a ⏳ status reaction); returns { task_ts, channel }
• slack_update_task: Post a threaded progress reply; with step/total_steps updates the parent's progress bar (no @-mentions)
• slack_complete_task: Final threaded reply + edits the parent into a ✅/❌ summary card, swaps the ⏳ reaction; the only task tool that may @-mention (notify_user)

Channels & History

• slack_list_channels: List accessible channels
• slack_get_channel_history: Get recent messages
• slack_get_thread_replies: Get thread conversations

Search

• slack_search_messages: Search across workspace
• slack_search_by_user: Find messages from specific users
• slack_search_by_date_range: Search within date ranges
• slack_search_files: Search for shared files

Users & Teams

• slack_list_users: List workspace members
• slack_get_user_by_name: Find users by name
• slack_get_user_info: Get detailed user information
• slack_get_user_status: Check user status
• slack_get_user_profile: Get full profile details

Files & Diagrams

• slack_upload_file: Upload files (images, documents, text) to a channel
• slack_send_diagram: Render HTML or Mermaid diagrams as PNG images and post to a channel (requires a one-time renderer install — npm install puppeteer, or playwright/wkhtmltoimage; not bundled, so the package install stays lean. Falls back to a clear "install a renderer" message if none is present. For plain tabular data use slack_send_table — no renderer needed.)

Reactions & Pins

• slack_add_reaction: Add emoji reactions
• slack_bulk_react_messages: React to multiple messages
• slack_pin_message: Pin important messages
• slack_unpin_message: Unpin messages

Productivity

• slack_create_reminder: Set reminders
• slack_list_reminders: View active reminders
• slack_get_workspace_stats: Get workspace analytics

Automatic Markdown Conversion

The slack_send_message tool now automatically converts common markdown formatting to Slack's mrkdwn format:

• Bold: **text** → *text*
• Links: [text](url) → <url|text>
• Strikethrough: ~~text~~ → ~text~
• Headers: # Header → *Header*
• Lists: - item → • item

This means Claude can use standard markdown formatting and it will appear correctly in Slack without manual conversion.

Session UX

These features keep agent-driven Slack usage cheap (in context tokens) and tidy.

Lean tool outputs (verbose flag)

The chatty read tools — slack_get_channel_history, slack_list_users, slack_list_channels, slack_search_messages, slack_search_by_user, slack_search_by_date_range, and slack_get_workspace_stats — return lean output by default. Lean output:

• Drops pretty-print whitespace and metadata exhaust (profile image URLs, team/bot IDs, edited markers, reaction blobs, full Block Kit JSON).
• Preserves message body text verbatim — content is never clipped or summarized.
• Caps how many items are returned and appends a footer like (showing 25 of 340 — pass verbose:true or a higher limit/cursor for the rest) so nothing is silently dropped.

Pass verbose: true on any of these tools to get the full raw API payload — the firehose is always one call away. Lean results are the main lever against the largest single source of session token cost (verbose results lingering in the context window).

ASCII tables vs. PNG tables

• slack_send_table renders a column-aligned monospace table inside a code block. Cheap (it's text), good for status grids and comparison matrices. Accepts an array of objects, a 2D array (first row = header), or a markdown pipe-table string.
• slack_send_diagram renders an HTML <table> as a PNG image — use it when you want a polished, presentation-grade table.

Threaded task lifecycle

Use slack_start_task → slack_update_task → slack_complete_task to run a long task in one thread instead of spamming a channel. The parent card shows a live progress bar and a ⏳ → ✅/❌ status reaction. Only slack_complete_task may @-mention the user (via notify_user); routine updates stay quiet.

Session identity (chat:write.customize)

The message-posting tools (slack_send_message, slack_send_formatted_message, slack_send_card, and the task tools) accept optional username, icon_emoji, and icon_url params so a session can post under a consistent identity like Claude · ChillMCP. Defaults can be set once via environment variables:

• SLACK_SESSION_USERNAME: default display name for posted messages
• SLACK_SESSION_ICON: default icon — either a :emoji: name or an image URL

Scope required: username/icon overrides require the chat:write.customize bot scope. If the scope is missing, Slack ignores the override and the message still posts under the app's default identity (degrades gracefully).

Advanced Features

Credentials (env-only)

There is no on-disk credential store — no keychain, no accounts.json, no encryption keys. The bot/user tokens live only in the env block of the MCP server entry and in process memory for the lifetime of the server. Rotating a token is just editing the config and restarting the server.

The only file the server writes is Legate poll state (~/.mcp-slack/legate-state/<call_sign>.json) — poll cursors and check-in status for the multi-session coordination tools. That is not credentials.

Performance Optimizations

• Efficient 120s TTL caching of users.list / conversations.list
• Lazy workspace-info hydration (auth.test on first use)
• Minimal startup overhead

Architecture

Single account, loaded from env. Multi-workspace is achieved by running multiple server entries:

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Claude    │────▶│ slack (server)   │────▶│ Workspace A │
│             │     │  SLACK_BOT_TOKEN │     └─────────────┘
│             │     └──────────────────┘
│             │     ┌──────────────────┐     ┌─────────────┐
│             │────▶│ slack-work       │────▶│ Workspace B │
│             │     │  SLACK_BOT_TOKEN │     └─────────────┘
└─────────────┘     └──────────────────┘

Troubleshooting

"No Slack bot token. Set SLACK_BOT_TOKEN…"

The server booted without a token. Add SLACK_BOT_TOKEN to the env block of this server's entry in ~/.claude.json (or .mcp.json) and restart.

Missing channels or users

Ensure your bot token has the necessary OAuth scopes:

• channels:read
• chat:write
• chat:write.customize (only needed for the username / icon_emoji / icon_url session-identity overrides)
• users:read
• files:read
• reactions:write (for the task-lifecycle status reactions)

Performance issues

• Check network connectivity to Slack
• Verify token permissions
• Review workspace size (very large workspaces may need pagination)

Development

Building from source

git clone https://github.com/ChinchillaEnterprises/ChillMCP.git
cd ChillMCP/mcp-slacker-v3
npm install
npm run build

Contributing

Issues and pull requests are welcome at the GitHub repository.

Roadmap — Next Tools Needed

~~Priority 1: slack_upload_file~~ — DONE (v3.1.0)

Upload files (images, documents, text) to a Slack channel. Uses Slack's files.uploadV2 API. Supports any file type. Returns file URL and permalink. Requires files:write bot scope.

~~Priority 2: slack_send_diagram~~ — DONE (v3.1.0)

Render an HTML/Mermaid diagram as a PNG image and post it to a Slack channel. Supports both raw HTML and Mermaid diagram syntax. Uses Puppeteer, Playwright, or wkhtmltoimage for rendering (auto-detects available engine). Temp files cleaned up after upload.

Rendering engine setup (one of these must be available):

# Recommended
npm install puppeteer

# Or alternatively
npm install playwright
# Or: brew install wkhtmltopdf

Priority 3: slack_send_formatted_message enhancement

The existing slack_send_formatted_message tool should be enhanced to support Block Kit layouts for richer Slack messages (headers, sections, dividers, context blocks).

Why These Matter

The Echelon project (Chinchilla AI's agent platform) uses AI agent teams that dynamically restructure per project phase. Before each phase, the team posts their formation diagram to Slack. Currently limited to ASCII art in code blocks. These tools enable posting actual rendered diagrams as images — much more professional and readable.

License

MIT License - see LICENSE file for details.

Credits

Built by Chinchilla Enterprises for the MCP ecosystem.