Slack MCP Server

A production-ready Model Context Protocol server for the Slack API.

This template lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients search Slack, list channels, read recent channel history, inspect users, fetch thread replies, and send messages through controlled Slack tools.

Built as a starter template for teams that want a secure baseline before adding company-specific Slack automation workflows.

Who this is for

This repository is useful for:

• developers building AI assistants for Slack workspaces,
• internal tools teams connecting Slack to AI agents,
• platform engineers who need a clean TypeScript MCP server example,
• agencies building Slack automation for clients,
• teams that want controlled Slack read/write tools for Claude, Cursor, or other MCP clients.

Features

• TypeScript + Express MCP server
• Slack OAuth 2.0 installation flow
• Optional static bot token bootstrap with SLACK_BOT_TOKEN
• Bearer-token protection for /mcp
• Rate limiting for MCP requests
• Health endpoint at /health
• Structured Pino logging
• Zod-based environment validation
• MCP tools for channels, messages, threads, users, and search
• Jest + Supertest test setup
• GitHub Actions CI workflow

Architecture

Claude Desktop / Cursor / Windsurf
        │
        │  HTTP POST /mcp
        │  Authorization: Bearer <MCP_API_KEY>
        ▼
  Express Server
        │
        ├── Pino HTTP logger
        ├── Rate limiter
        ├── MCP API key middleware
        │
        ▼
   MCP SDK Handler
        │
        ├── slack_list_channels       ─┐
        ├── slack_get_channel_history ─┤
        ├── slack_send_message        ─┤──► Slack Web API
        ├── slack_get_thread_replies  ─┤
        ├── slack_get_user_info       ─┤
        ├── slack_list_users          ─┤
        └── slack_search_messages     ─┘

  OAuth Flow
        GET /auth/slack           → Slack install screen
        GET /auth/slack/callback  → token exchange + token storage
        GET /auth/status          → installed workspace summary

  GET /health → Slack API + token-store dependency status

See the larger diagram in docs/architecture.md.

Source Code

The complete production-ready Slack MCP Server template is available on GitHub.

Repository:

https://github.com/kamolc4/slack-mcp-server

The repository includes:

• Complete TypeScript source code
• Slack OAuth implementation
• MCP tools
• GitHub Actions CI
• Jest test suite
• MIT License
• Claude Desktop & Cursor configuration
• Production deployment examples

Fork the repository or download it as a ZIP to start building immediately.

Available MCP tools

Tool	Purpose
slack_list_channels	List public and private channels in the connected Slack workspace.
slack_get_channel_history	Fetch recent messages from a Slack channel.
slack_send_message	Post a message to a channel, optionally as a thread reply.
slack_get_thread_replies	Fetch replies in a Slack message thread.
slack_get_user_info	Get profile details for a Slack user by ID.
slack_list_users	List workspace users.
slack_search_messages	Search Slack messages using Slack search syntax.

Quick start

1. Install dependencies

# Clone repository
git clone https://github.com/kamolc4/slack-mcp-server.git

cd slack-mcp-server

# Install dependencies
npm ci

2. Configure environment

cp .env.example .env

Edit .env:

PORT=3000
NODE_ENV=development
LOG_LEVEL=info
BASE_URL=http://localhost:3000

MCP_API_KEY=replace-with-a-long-random-secret
SESSION_SECRET=replace-with-a-long-random-session-secret

SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-client-secret
SLACK_SIGNING_SECRET=your-slack-signing-secret
SLACK_REDIRECT_URI=http://localhost:3000/auth/slack/callback

RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=100

3. Run locally

npm run dev

4. Install the Slack app

Open this URL in your browser:

http://localhost:3000/auth/slack

After successful installation, check status:

curl http://localhost:3000/auth/status

5. Check health

curl http://localhost:3000/health

Slack OAuth setup

In the Slack API dashboard:

1. Create a new Slack app.
2. Add this redirect URL:

http://localhost:3000/auth/slack/callback

3. Copy the client ID, client secret, and signing secret into .env.
4. Add the OAuth scopes required by the tools you expose.

Recommended bot scopes for this starter template:

channels:read
channels:history
users:read
search:read
chat:write

For production, set SLACK_REDIRECT_URI to your deployed callback URL, for example:

https://your-domain.com/auth/slack/callback

Optional static bot token mode

For local single-workspace testing, you can skip OAuth and use an existing bot token:

SLACK_BOT_TOKEN=xoxb-your-token

The server will call auth.test at startup and bootstrap the token if it is valid.

Connect to Claude Desktop

Build the server first:

npm run build
npm start

Then add an MCP server entry in your Claude Desktop configuration:

{
  "mcpServers": {
    "slack": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-your-mcp-api-key"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Connect to Cursor

In Cursor, add a new MCP server using the HTTP endpoint:

{
  "name": "slack",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer replace-with-your-mcp-api-key"
  }
}

Then restart Cursor or reload the MCP server list.

Security notes

This template is safer than a minimal demo, but you should harden it before production use.

Recommended production changes:

• Replace the in-memory token store in src/auth.ts with Redis, Postgres, or another encrypted durable store.
• Store Slack bot tokens encrypted at rest.
• Store secrets in a managed secret manager, not in plain .env files.
• Rotate MCP_API_KEY regularly.
• Add per-user or per-workspace authorization if multiple users will access the server.
• Restrict write tools such as slack_send_message behind approvals.
• Add audit logs for every tool call.
• Use HTTPS in production.
• Review Slack scopes and remove anything your use case does not need.

Security Review

Verify this server with MCPForge:

https://www.mcpforge.tech/verify

MCPForge can help review:

• exposed tools,
• authentication behavior,
• health checks,
• compatibility with MCP clients,
• risk level of write operations,
• security posture before publishing or deployment.

After verification, you can link your public report from this README:

[![Verified by MCPForge](https://www.mcpforge.tech/api/servers/slack-mcp-server/badge)](https://www.mcpforge.tech/verified/slack-mcp-server)

Read the complete guide on MCPForge:

https://www.mcpforge.tech/blog/slack-mcp-server

Deployment

A common production setup:

1. Deploy this service to Railway, Render, Fly.io, AWS, GCP, Azure, or a private Kubernetes cluster.
2. Configure environment variables in the hosting provider.
3. Set BASE_URL to your public HTTPS URL.
4. Set SLACK_REDIRECT_URI to https://your-domain.com/auth/slack/callback.
5. Add the same callback URL in the Slack app dashboard.
6. Run the Slack OAuth installation flow once to connect the workspace.
7. Verify /health and /mcp before connecting production AI clients.
8. Run a public or private verification with MCPForge.

Local development commands

npm run lint
npm run typecheck
npm test
npm run build

API endpoints

Method	Path	Description
GET	/health	Health and Slack connectivity check.
GET	/auth/slack	Start Slack OAuth installation.
GET	/auth/slack/callback	Slack OAuth callback.
GET	/auth/status	Installed workspace status.
POST	/mcp	MCP endpoint protected by Authorization: Bearer <MCP_API_KEY>.

Contributing

Contributions are welcome.

To improve this Slack MCP Server template, please open an issue or submit a pull request.

Releases

Latest stable release:

v1.0.0

See the Releases page for the full changelog.

License

MIT — see LICENSE.

Related MCP Server Templates

Looking for other production-ready MCP Server templates?

• GitHub MCP Server
• Slack MCP Server
• Stripe MCP Server
• Notion MCP Server
• Shopify MCP Server
• HubSpot MCP Server
• PostgreSQL MCP Server

Browse the complete collection:

https://www.mcpforge.tech/code