Slack Local MCP

A lightweight Model Context Protocol (MCP) server for Slack automation using cookie-based authentication.

Why Slack Local MCP? Other MCP servers require creating a Slack app or bot, which can be overkill when you just want to automate simple workspace actions. Slack Local MCP lets you connect to Slack directly and boost your productivity with automation — no need to deal with complex app setup or OAuth tokens.

⚠️ Heads up: Slack Local MCP uses your Slack web cookie for authentication, so handle it carefully and avoid exposing it publicly.

Features

🚀 Core Capabilities

• Send Messages: Post to channels, send DMs, or reply to threads
• Schedule Messages: Use Slack's native scheduling to post messages at specific times
• Fetch Conversations: Retrieve channel messages or thread replies for AI summarization
• Add Reactions: React to messages with emoji

🔐 Authentication

Uses cookie-based authentication with your Slack web session token for quick setup without OAuth configuration. Perfect for personal automation and local development.

Note: For production use cases or team-wide deployments, consider using OAuth-based Slack MCP servers instead.

Quick Start

Prerequisites

• Node.js 18+ installed
• Active Slack workspace access

Installation

Option 1: Using npx (Recommended)

The easiest way to use this MCP server is via npx, which doesn't require manual installation:

npx -y slack-local-mcp

When configuring in your MCP settings, use:

{
  "mcpServers": {
    "slack-local": {
      "command": "npx",
      "args": [
        "-y",
        "slack-local-mcp"
      ],
      "env": {
        "SLACK_COOKIE_D": "xoxd-your-cookie-value-here",
        "SLACK_WORKSPACE_URL": "https://your-workspace.slack.com"
      }
    }
  }
}

Option 2: Manual Installation

If you prefer to install manually:

1. Clone or download this repository:

   git clone https://github.com/yourusername/slack-local-mcp.git
   cd slack-local-mcp
   npm install
   npm run build
   

2. Extract your Slack cookie (detailed guide below)

3. Configure the MCP server in your settings (see Configuration section)

4. Start using natural language to control Slack!

Cookie Extraction Guide

⚠️ Security Warning: Your Slack cookie provides full access to your workspace. Keep it private and never share it.

Steps to Extract Cookie

1. Open Slack in your web browser (works best in Chrome/Edge/Firefox)

2. Open Developer Tools:

   • Windows/Linux: Press F12 or Ctrl+Shift+I
   • Mac: Press Cmd+Option+I

3. Navigate to Storage/Cookies:

   • In Chrome/Edge: Click Application tab → Storage → Cookies → https://app.slack.com
   • In Firefox: Click Storage tab → Cookies → https://app.slack.com

4. Find the "d" cookie:

   • Look for a cookie named exactly d
   • The value starts with xoxd-
   • Example (unencoded): xoxd-1234567890123-1234567890123-AbCdEfGhIjKlMnOpQrStUvWxYz...

5. Copy the entire value:

   • Click on the cookie value to select it
   • Copy it exactly as shown (it should be URL-encoded with %2B, %2F, %3D characters)
   • Important: Use the URL-encoded version shown in the browser, not a decoded version

6. Keep this value secure - you'll need it for configuration

Cookie Validity

• Cookies typically last for weeks or months
• If you log out of Slack, the cookie becomes invalid
• You'll need to extract a new cookie if you clear browser data
• The server will show an authentication error if the cookie expires

Configuration

MCP Settings

Add this configuration to your MCP settings file:

Location: your_mcp_client/mcp_settings.json

For npx Installation (Recommended)

{
  "mcpServers": {
    "slack-local": {
      "command": "npx",
      "args": [
        "-y",
        "slack-local-mcp"
      ],
      "env": {
        "SLACK_COOKIE_D": "xoxd-your-cookie-value-here",
        "SLACK_WORKSPACE_URL": "https://your-workspace.slack.com",
        "SLACK_USER_AGENT": "Mozilla/5.0 (optional)",
        "LOG_LEVEL": "info",
        "SLACK_USER_CACHE_FILE": "/tmp/slack-mcp-users-cache.json",
        "SLACK_USER_CACHE_TTL": "86400"
      },
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": []
    }
  }
}

For Manual Installation

{
  "mcpServers": {
    "slack-local": {
      "command": "node",
      "args": [
        "/path/to/slack-local-mcp/build/index.js"
      ],
      "env": {
        "SLACK_COOKIE_D": "xoxd-your-cookie-value-here",
        "SLACK_WORKSPACE_URL": "https://your-workspace.slack.com",
        "SLACK_USER_AGENT": "Mozilla/5.0 (optional)",
        "LOG_LEVEL": "info",
        "SLACK_USER_CACHE_FILE": "/tmp/slack-mcp-users-cache.json",
        "SLACK_USER_CACHE_TTL": "86400"
      },
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": []
    }
  }
}

Configuration Parameters:

• SLACK_COOKIE_D (required): Your Slack d cookie value (URL-encoded, starts with xoxd-)
• SLACK_WORKSPACE_URL (required): Your workspace URL (e.g., https://mycompany.slack.com)
• SLACK_USER_AGENT (optional): Custom User-Agent string (defaults to Slack-MCP-Client/1.0)
• LOG_LEVEL (optional): Logging level - debug, info, warn, or error (defaults to info)
• SLACK_USER_CACHE_FILE (optional): Path to user list cache file (defaults to /tmp/slack-mcp-users-cache.json)
• SLACK_USER_CACHE_TTL (optional): Cache time-to-live in seconds (defaults to 86400 = 24 hours)

Important Notes:

• Use the URL-encoded cookie value from your browser (contains %2B, %2F, %3D)
• The workspace URL should match your Slack workspace address
• Cookie and workspace URL are required for authentication
• User-Agent can be customized if needed (e.g., to match your browser's UA)
• This authentication method is ideal for personal use and local automation

Available Tools

1. send_message

Send a message to a Slack channel.

Parameters:

• channel (required): Channel ID (e.g., C1234567890) or name (e.g., general)
• text (required): Message content (up to 40,000 characters)
• thread_ts (optional): Thread timestamp to reply to
• unfurl_links (optional): Enable link previews (default: true)

Example Commands:

• "Send a message to #general saying 'Hello team!'"
• "Post 'Meeting in 5 minutes' to the project-alpha channel"
• "Send a message to C1234567890 with the latest updates"

---

2. send_direct_message

Send a direct message to a specific user.

Parameters:

• user (required): User ID (e.g., U1234567890) or username
• text (required): Message content
• thread_ts (optional): Continue a DM thread

Example Commands:

• "Send a DM to @john saying 'Can we talk about the proposal?'"
• "Direct message U1234567890 with 'Thanks for your help!'"

---

3. reply_to_thread

Reply to a specific thread in a channel.

Parameters:

• channel (required): Channel ID where the thread exists
• thread_ts (required): Parent message timestamp
• text (required): Reply content
• broadcast (optional): Also post to main channel (default: false)

Example Commands:

• "Reply to thread 1234567890.123456 in #general with 'I agree!'"
• "Add a reply to that thread saying 'Great idea!'"

---

4. schedule_message

Schedule a message to be sent at a future time using Slack's native scheduling.

⚠️ Important: This tool requires a bot token (starting with xoxb-) to function. Cookie-based authentication (using xoxd- tokens) does not support message scheduling. The tool will return an error when used with cookie authentication.

Parameters:

• channel (required): Channel ID
• text (required): Message content
• post_at (required): Unix timestamp for delivery
• thread_ts (optional): Schedule a thread reply

Constraints:

• Must be at least 1 minute in the future
• Cannot be more than 120 days ahead
• Scheduled messages can be managed in Slack's scheduled messages UI
• Requires bot token authentication (not available with cookie auth)

Example Commands:

• "Schedule a message to #general tomorrow at 9am saying 'Daily standup reminder'"
• "Post 'Happy Friday!' to #team next Friday at 5pm"

---

5. fetch_channel_messages

Retrieve recent messages from a channel for summarization or context.

Parameters:

• channel (required): Channel ID or name
• limit (optional): Number of messages (default: 50, max: 200)
• oldest (optional): Oldest timestamp to include
• latest (optional): Latest timestamp to include

Returns:

• Array of message objects
• formatted_text: Human-readable format optimized for AI processing

Example Commands:

• "Fetch the last 50 messages from #general"
• "Get recent messages from project-updates for summarization"
• "Show me the last 100 messages from C1234567890"

---

6. fetch_thread_messages

Get all messages from a specific thread.

Parameters:

• channel (required): Channel ID
• thread_ts (required): Thread parent timestamp
• limit (optional): Max messages (default: 100, max: 200)

Returns:

• Array of thread replies in chronological order
• Includes the parent message
• formatted_text: Ready for AI summarization

Example Commands:

• "Fetch all replies from thread 1234567890.123456 in #general"
• "Get the conversation from that thread for summarization"
• "Show me what was discussed in thread 1705234567.890123"

---

7. add_reaction

Add an emoji reaction to a message.

Parameters:

• channel (required): Channel ID where the message exists
• timestamp (required): Message timestamp
• reaction (required): Emoji name without colons (e.g., thumbsup, tada, rocket)

Example Commands:

• "Add a thumbsup reaction to message 1234567890.123456 in #general"
• "React with 🎉 to that message"
• "Add a rocket emoji to the latest message"

Usage Examples

Example 1: Daily Team Update

You: "Fetch the last 20 messages from #engineering and summarize the key discussions"

AI: [Uses fetch_channel_messages]
"I've retrieved the messages. Here's a summary:
- Team discussed the new API design
- Bug fix for login issue was deployed
- Code review scheduled for tomorrow at 2pm"

You: "Send a message to #engineering summarizing these points"

AI: [Uses send_message]
"Message sent to #engineering with the summary!"

Example 2: Schedule Reminders

You: "Schedule a message to #team-standup tomorrow at 9am saying 'Daily standup in the war room!'"

AI: [Uses schedule_message]
"Message scheduled for tomorrow at 9:00 AM in #team-standup"

Example 3: Thread Management

You: "What's being discussed in thread 1705234567.890123 in #project-alpha?"

AI: [Uses fetch_thread_messages]
"The thread contains 15 messages discussing the Q4 roadmap priorities."

You: "Reply to that thread with 'I support option 2'"

AI: [Uses reply_to_thread]
"Reply posted to the thread!"

Troubleshooting

"Authentication Error" or "Invalid Cookie"

Cause: Your cookie has expired, invalid, or not URL-encoded properly.

Solution:

1. Extract a fresh cookie from your browser
2. Verify the cookie is URL-encoded (should contain %2B, %2F, %3D characters)
3. Ensure SLACK_WORKSPACE_URL matches your workspace
4. Update both values in MCP settings
5. Restart your MCP client

Common Issues:

• Using a decoded cookie value (missing % encoded characters)
• Wrong workspace URL
• Cookie expired (log out and back in to get a fresh one)

"Channel Not Found"

Cause: Invalid channel ID or you don't have access.

Solution:

• Verify the channel ID is correct (starts with C)
• Check that you're a member of the channel
• Use the channel name instead (e.g., general)

"Rate Limited"

Cause: Too many API requests in a short time.

Solution:

• Wait a few seconds between requests
• The server implements automatic retry with backoff
• Reduce the frequency of operations

"Message Too Long"

Cause: Message exceeds 40,000 characters.

Solution:

• Split your message into multiple parts
• Use attachments for longer content (future feature)

Server Not Appearing in MCP

Cause: Configuration or build issue.

Solution:

1. Verify the server path in MCP settings is correct
2. Run npm run build in the server directory
3. Check that build/index.js exists and is executable
4. Restart your MCP client
5. Check the MCP server logs for errors

Security Best Practices

Do's ✅

• Store your cookie in environment variables only
• Use a dedicated browser profile for Slack if concerned
• Regularly rotate your cookie (log out and back in)
• Monitor your Slack activity for unexpected actions
• Keep this server code private

Don'ts ❌

• Never commit your cookie to version control
• Don't share your cookie with others
• Don't use this in production systems (use OAuth instead)
• Don't store cookies in plain text files
• Don't use on shared computers without logging out

Architecture

This server is built with:

• TypeScript: Type-safe development
• MCP SDK: Standard protocol implementation
• Axios: Reliable HTTP client with interceptors
• Zod: Runtime validation and type inference

Development

Building from Source

cd /path/to/slack-local-mcp
npm install
npm run build

Running Tests

The project includes a comprehensive test suite that validates all functionality:

# Run all tests
SLACK_COOKIE_D='your-cookie' SLACK_WORKSPACE_URL='https://workspace.slack.com' node test-slack-mcp.js

# Optional: Specify test channel and custom user agent
TEST_CHANNEL='C1234567890' SLACK_USER_AGENT='Custom-Agent' SLACK_COOKIE_D='your-cookie' SLACK_WORKSPACE_URL='https://workspace.slack.com' node test-slack-mcp.js

**Note**: These tests use your actual Slack workspace. Scheduled messages require bot token authentication and will be skipped when using cookie authentication.

Test Coverage:

• ✅ Client initialization
• ✅ Authentication (cookie + token)
• ✅ Send message to channel
• ✅ Reply to thread
• ✅ Add reaction to message
• ✅ Fetch channel messages
• ✅ Fetch thread messages
• ✅ Schedule message (skipped with cookie auth)
• ✅ Send direct message
• ✅ Custom User-Agent configuration

Contributing

Contributions are welcome! This project focuses on simple, cookie-based authentication for personal automation. For enterprise features, consider contributing to OAuth-based alternatives.

License

MIT License - See LICENSE file for details

Acknowledgments

• Built on the Model Context Protocol
• Slack API documentation: https://api.slack.com/
• Cookie authentication approach inspired by: https://papermtn.co.uk/retrieving-and-using-slack-cookies-for-authentication/

Why "Local"?

The "Local" in Slack Local MCP emphasizes that this server:

• Runs on your local machine
• Uses your personal Slack session
• Doesn't require server-side app configuration
• Is perfect for individual productivity and automation

For team-wide deployments or production systems, consider OAuth-based alternatives.

---

Happy Slacking! 🚀