@chinchillaenterprises/mcp-slack

# MCP Slack Server A powerful multi-account Model Context Protocol (MCP) server for Slack that enables seamless workspace switching and persistent credential storage. ## Features - 🔄 **Multi-Account Support**: Switch between multiple Slack workspaces at runtime - 🔐 **Secure Credential Storage**: Uses native OS keychains with encrypted file-based fallback - ⚡ **Fast Performance**: <200ms startup time for 10+ workspaces - 🛡️ **Dual Storage System**: Automatic fallback to encrypted file storage if keychain unavailable - 🔍 **Comprehensive Slack Tools**: 40+ tools for messages, channels, users, files, and more - 📸 **File Upload & Diagrams**: Upload files and render HTML/Mermaid diagrams as images directly to Slack - 📁 **Reliable Persistence**: Accounts persist across Claude sessions - ✨ **Automatic Markdown Conversion**: Converts common markdown formatting to Slack's mrkdwn format ## Installation ### Using Claude Desktop ```bash claude mcp add slack -- npx @chinchillaenterprises/mcp-slack ``` ### Using Claude Code (Recommended) ```bash # Install with user scope for persistence across sessions claude mcp add slack -s user -- npx @chinchillaenterprises/mcp-slack # Or with environment variables for default workspace claude mcp add slack -s user -e DEFAULT_BOT_TOKEN=xoxb-YOUR-BOT-TOKEN -e DEFAULT_TEAM_ID=YOUR-TEAM-ID -- npx @chinchillaenterprises/mcp-slack ``` ### Manual Installation ```bash npm install -g @chinchillaenterprises/mcp-slack ``` ## Configuration ### Environment Variables For the default workspace: - `DEFAULT_BOT_TOKEN`: Slack bot token (xoxb-...) - `DEFAULT_USER_TOKEN`: Slack user token (xoxp-...) - `DEFAULT_TEAM_ID`: Slack team/workspace ID - `DEFAULT_ACCOUNT_NAME`: Display name for the workspace ## Usage ### Account Management The V3 architecture introduces powerful account management capabilities: - **list_accounts**: View all configured workspaces - **switch_account**: Change active workspace at runtime - **add_account**: Add new workspace credentials - **remove_account**: Remove workspace from configuration - **update_account**: Update existing workspace credentials ### 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_edit_message`: Edit existing messages - `slack_delete_message`: Delete messages - `slack_schedule_message`: Schedule messages for later - `slack_forward_message`: Forward messages between channels #### 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 #### 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. ## Advanced Features ### Persistent Storage The server uses a dual-storage system for maximum reliability: 1. **Primary Storage**: Native OS keychain - **macOS**: Keychain Access - **Windows**: Credential Manager - **Linux**: Secret Service API 2. **Fallback Storage**: Encrypted file storage - Location: `~/.mcp-slack/accounts.json` - Credentials encrypted using AES-256-CBC - Automatic failover if keychain unavailable - Permissions restricted to user only (0600) ### Data Security - Bot tokens and user tokens are encrypted at rest - Encryption key stored separately with restricted permissions - No plaintext credentials on disk - Automatic cleanup of stale sessions ### Performance Optimizations - Lazy loading of workspace configurations - Efficient caching of API responses - Minimal startup overhead ## Architecture MCP Slack Server implements the Account Manager Tools Pattern with dual storage: ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Claude │────▶│ MCP Server │────▶│ Slack │ │ Desktop │ │ │ │ Workspaces │ └─────────────┘ └──────────────┘ └─────────────┘ │ ┌───────┴───────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ OS Keychain │ │ Encrypted │ │ Storage │ │ File Storage │ └──────────────┘ └──────────────┘ Primary Fallback ``` ## Troubleshooting ### "Secure storage unavailable" This warning appears when keychain access is denied or unavailable. The server will continue working with temporary storage. ### Missing channels or users Ensure your bot token has the necessary OAuth scopes: - `channels:read` - `chat:write` - `users:read` - `files:read` ### Performance issues - Check network connectivity to Slack - Verify token permissions - Review workspace size (very large workspaces may need pagination) ## Development ### Building from source ```bash 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](https://github.com/ChinchillaEnterprises/ChillMCP). ## 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): ```bash # 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 ForgeClaw 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](https://github.com/ChinchillaEnterprises) for the MCP ecosystem.