easy-slack-mcp

easy-slack-mcp

<img src="images/slack.jpg" alt="Slack Logo" style="width: 100%;"/>

<h2 style="font-size: 1.5em; margin: 1em 0;">🚀 The Easiest way to run Slack MCP</h2>

Slack integration for AI assistants - Connect Cursor, Claude Desktop, and other MCP-compatible tools directly to Slack. Send messages, read channels, manage users, and automate workflows with AI.

      

---

📦 What We Provide

| Feature | Description | |---|---| | MCP Server | Full Model Context Protocol integration for AI assistants (Cursor, Claude Desktop, etc.) | | REST API | Complete Slack API wrapper with OpenAPI/Swagger documentation | | Message Management | Send, update, and delete messages in channels and DMs | | Channel Operations | List, create, view details, and read message history for channels | | User Management | List users, get user info, and access user profiles | | File Operations | Upload files, list files, and get file information | | Reactions | Add and remove emoji reactions to messages | | Interactive Docs | Swagger UI for exploring and testing all endpoints | | Zero Configuration | Run with a single command - just provide your Slack bot token | | Production Ready | Built on easy-mcp-server framework |

---

🚀 Quick Start

SLACK_BOT_TOKEN=xoxb-your-token-here npx easy-slack-mcp

That's it! The server runs on:

| Service | URL | Notes | |---|---|---| | REST API | http://localhost:8887 | Base for all endpoints | | API Docs (Swagger UI) | http://localhost:8887/docs | Interactive documentation | | MCP Server | http://localhost:8888 | For MCP-compatible clients |

---

📋 Detailed Configuration

Getting Your Slack Bot Token

1. Go to https://api.slack.com/apps
2. Click "Create New App" → "From scratch"
3. Give your app a name and select your workspace
4. Click "Create App"
5. Navigate to "OAuth & Permissions" in the sidebar
6. Scroll down to "Bot Token Scopes" and add the following scopes:

• chat:write - Send messages
• chat:write.public - Send to channels bot isn't in
• channels:read - View channel info
• channels:history - Read channel messages
• users:read - View users
• users:read.email - View email addresses
• files:write - Upload files
• files:read - View files
• reactions:write - Add reactions
• reactions:read - View reactions

1. Scroll to the top and click "Install to Workspace"
2. Authorize the app
3. Copy your Bot User OAuth Token (starts with xoxb-)

Using Environment Variables

Instead of passing the token inline, you can use a .env file for persistent configuration:

# Create .env file
echo "SLACK_BOT_TOKEN=xoxb-your-token-here" > .env

# Run (it will automatically load .env)
npx easy-slack-mcp

Local Installation

For a permanent local installation:

# Install locally
npm install easy-slack-mcp

# Create .env file
echo "SLACK_BOT_TOKEN=xoxb-your-token-here" > .env

# Run
npm start
# OR
npx easy-slack-mcp

---

💻 Use in Cursor / Claude Desktop

Option A: Use as npm package (Recommended)

For Cursor:

1. Open Cursor Settings → Features → Model Context Protocol
2. Click "Edit Config"
3. Add this to your MCP config:

{
  "mcpServers": {
    "easy-slack-mcp": {
      "command": "npx",
      "args": ["-y", "easy-slack-mcp"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

For Claude Desktop:

1. Open ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)

or %APPDATA%\Claude\claude_desktop_config.json (Windows)

1. Add the same configuration above

For any MCP client: The server runs automatically when invoked via npx easy-slack-mcp

Client configuration paths

| Client | Platform | Config Location | |---|---|---| | Cursor | macOS/Windows/Linux | Settings → Features → Model Context Protocol | | Claude Desktop | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Option B: Local Installation

If you prefer a local setup:

# Install locally
npm install easy-slack-mcp

# Create .env file
echo "SLACK_BOT_TOKEN=xoxb-your-token-here" > .env

# Run it
npx easy-slack-mcp

Then configure your MCP client to run: ``bash npx easy-slack-mcp ``

---

📡 Using the REST API

Once the server is running, you have full access to Slack via REST endpoints.

🔍 Interactive API Documentation

| Name | URL | Best for | |---|---|---| | Swagger UI | http://localhost:8887/docs | Browsing endpoints, trying requests, viewing schemas | | OpenAPI JSON | http://localhost:8887/openapi.json | Import into Postman/Insomnia or tooling |

📝 Common API Examples

Send a Message

curl -X POST http://localhost:8887/slack/messages \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "C1234567890",
    "text": "Hello from easy-slack-mcp!"
  }'

List Channels

curl "http://localhost:8887/slack/conversations/list?types=public_channel"

Get Channel History

curl "http://localhost:8887/slack/conversations/history?channel=C1234567890&limit=20"

List Users

curl "http://localhost:8887/slack/users/list"

Upload a File

curl -X POST http://localhost:8887/slack/files/upload \
  -H "Content-Type: application/json" \
  -d '{
    "channels": "C1234567890",
    "filename": "report.txt",
    "content": "File content here"
  }'

---

📚 All Available Endpoints

| Category | Method | Path | Description | |---|---|---|---| | Messages | POST | /slack/messages | Send a message | | Messages | POST | /slack/messages/update | Update a message | | Messages | POST | /slack/messages/delete | Delete a message | | Conversations | GET | /slack/conversations/list | List all channels | | Conversations | GET | /slack/conversations/info | Get channel details | | Conversations | POST | /slack/conversations/create | Create a channel | | Conversations | GET | /slack/conversations/history | Get message history | | Users | GET | /slack/users/list | List workspace users | | Users | GET | /slack/users/info | Get user details | | Users | GET | /slack/users/profile | Get user profile | | Files | POST | /slack/files/upload | Upload a file | | Files | GET | /slack/files/list | List files | | Files | GET | /slack/files/info | Get file info | | Reactions | POST | /slack/reactions/add | Add a reaction | | Reactions | POST | /slack/reactions/remove | Remove a reaction | | Authentication | GET | /slack/auth/test | Test authentication | | System | GET | /health | Health check | | System | GET | /api-info | API information | | System | GET | /openapi.json | OpenAPI specification | | System | GET | /docs | Swagger UI documentation |

---

⚙️ Advanced Configuration

Environment Variables

All configuration can be set via environment variables:

| Name | Required | Default | Description | |---|---|---|---| | SLACK_BOT_TOKEN | Yes | — | Bot User OAuth Token (starts with xoxb-) | | SLACK_APP_TOKEN | No | — | App-level token for Socket Mode (starts with xapp-) | | SLACK_SIGNING_SECRET | No | — | Verifies Slack request signatures for Events/API Gateway | | EASY_MCP_SERVER_PORT | No | 8887 | REST API port | | EASY_MCP_SERVER_MCP_PORT | No | 8888 | MCP server port |

Example .env content:

SLACK_BOT_TOKEN=xoxb-your-token-here
# Optional
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret
EASY_MCP_SERVER_PORT=8887
EASY_MCP_SERVER_MCP_PORT=8888

Required Slack Scopes

See the Detailed Configuration section above for setup steps. The bot typically needs these scopes:

| Scope | Purpose | |---|---| | chat:write | Send messages as the bot | | chat:write.public | Post to channels the bot isn’t a member of | | channels:read | View basic channel information | | channels:history | Read channel messages | | users:read | View users in the workspace | | users:read.email | View user email addresses | | files:write | Upload files | | files:read | View files | | reactions:write | Add reactions to messages | | reactions:read | View reactions on messages |

---

🎯 Use Cases

In Cursor / Claude Desktop

• "Send a message to #general about the project update"
• "What's the latest activity in #support channel?"
• "Find user @john and show their profile"
• "Summarize this week's messages in #engineering"

Via REST API

• Build custom integrations
• Automate Slack workflows
• Create Slack bots
• Integrate with other services

Via Swagger UI

• Explore endpoints visually
• Test API calls
• Understand request/response formats
• Share API documentation

---

📖 Learn More

• Easy MCP Server Framework:
• GitHub Repository
• npm Package
• Full Setup Guide: See mcp/resources/slack-quick-start.md
• Complete API Docs: See mcp/resources/api-documentation.md
• Slack API: https://api.slack.com/methods
• Model Context Protocol: https://modelcontextprotocol.io/

---

📦 Package Info

| Item | Link/Value | |---|---| | npm | easy-slack-mcp | | Repository | GitHub | | License | MIT |

---

🆘 Need Help?

1. Check Swagger UI: http://localhost:8887/docs
2. Test authentication: curl http://localhost:8887/slack/auth/test
3. Check server health: curl http://localhost:8887/health
4. Review the setup guide
5. For customization or support, contact info@easynet.world

---

Ready to automate Slack with AI? Get started:

# Install and run directly
npx easy-slack-mcp

# Or install locally for project use
npm install easy-slack-mcp
npm start

---

Powered by easy-mcp-server framework