slack-mcp

Slack MCP server built from the skeleton-mcp base.

This project exposes Slack Web API operations as MCP tools with:

• stdio and HTTP transport support
• HTTP bearer-token protection for /mcp
• optional admin authorization gates for mutating tools
• Vault/Postgres scaffolding preserved from the original skeleton

What It Does

The server currently focuses on Slack operations:

• Validate Slack token context
• List conversations
• Read conversation history
• Read user profile info
• Post messages
• Call any Slack Web API method via a generic tool

Slack MCP Tool Catalog

Read-only tools:

• slack_connection_info
• slack_scope_info
• slack_list_methods
• slack_auth_test
• slack_conversations_list
• slack_conversation_history
• slack_user_info

Mutating tools:

• slack_post_message
• slack_api_call (only guarded when the method is mutating)

Authorization behavior:

• If MCP_ADMIN_AUTH_KEY is set, mutating tools require authorizationKey.
• Guarded mutating method names for slack_api_call include chat.postMessage and common write operations like reactions.add, pins.add, conversations.archive, etc.

Slack API Notes

Configured Slack client:

• Base URL defaults to https://slack.com/api
• Bot token is required via SLACK_BOT_TOKEN

Implemented method wrappers:

• auth.test
• conversations.list
• conversations.history
• users.info
• chat.postMessage

Generic method execution:

• slack_api_call sends POST to /<methodName> with params JSON payload
• Example methodName: conversations.info, users.list, chat.postMessage

Required Slack Scopes

Typical scopes you should grant your Slack app for these tools:

• chat:write for slack_post_message
• channels:read, groups:read, im:read, mpim:read for conversations.list
• channels:history, groups:history, im:history, mpim:history for conversations.history
• users:read for users.info
• users:read.email if you need email in users.info responses

Exact required scopes can vary by workspace and conversation type.

Environment Variables

Slack-specific:

• SLACK_BOT_TOKEN (required)
• SLACK_API_BASE_URL (default: https://slack.com/api)
• SLACK_TIMEOUT_MS (default: 15000)

Core app:

• APP_NAME
• MCP_SERVER_NAME (default: slack-mcp)
• MCP_SERVER_VERSION
• MCP_ADMIN_AUTH_KEY
• MCP_TRANSPORT_MODE (stdio, http, both)

HTTP transport:

• MCP_HTTP_HOST
• MCP_HTTP_PORT
• MCP_HTTP_PATH
• MCP_HTTP_HEALTH_PATH
• MCP_HTTP_AUTH_MODE
• MCP_HTTP_AUTH_TOKENS
• MCP_HTTP_TRUST_PROXY
• MCP_HTTP_ALLOWED_ORIGINS
• MCP_HTTP_ALLOWED_IPS
• MCP_HTTP_MAX_BODY_BYTES
• MCP_HTTP_RATE_LIMIT_WINDOW_MS
• MCP_HTTP_RATE_LIMIT_MAX_REQUESTS

For full defaults and examples, see .env.example.

Quick Start

1. Install dependencies:

npm install

2. Copy env file and set Slack token:

cp .env.example .env

Set at minimum:

• SLACK_BOT_TOKEN=xoxb-...

3. Start MCP server:

npm run start:stdio

Or HTTP mode:

npm run start:http

4. Run tests:

npm test

Registering in MCP Clients

VS Code (stdio)

Example .vscode/mcp.json entry:

{
  "command": "npm",
  "args": ["run", "start:stdio"],
  "cwd": "/path/to/slack-mcp"
}

HTTP-capable clients

Run:

npm run start:http

Default endpoint:

• MCP: http://127.0.0.1:3000/mcp
• Health: http://127.0.0.1:3000/healthz

HTTP Security Model

• Every /mcp request requires Authorization: Bearer <token>
• Token validation currently uses configured MCP_HTTP_AUTH_TOKENS unless other auth sources are wired
• Rate limit and body-size protections are enforced by src/http/server.js

Note:

• TLS termination is intended at reverse proxy/load balancer level in this process mode.

External Services Mode

The repository still supports an app-only startup profile via docker-compose.external.yml when using external Vault and Postgres services.

Required variables in that mode include:

• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• VAULT_ADDR
• VAULT_TOKEN

Start with:

docker compose -f docker-compose.external.yml up -d

Project Structure

Primary runtime files:

• src/index.js: stdio startup
• src/http/index.js: HTTP startup
• src/http/server.js: HTTP transport/auth/rate limiting
• src/mcp/server.js: MCP tool registration and auth checks
• src/services/targetService.js: SlackServiceClient adapter
• src/config/env.js: env parsing/validation

Skeleton infrastructure (preserved):

• src/services/vault.js
• src/services/configStore.js
• docker-compose.yml
• docker-compose.external.yml
• vault-production/

Testing

Current tests include:

• Slack MCP tool behavior and mutating auth requirements
• HTTP transport auth/initialize/health behavior
• Existing skeleton Vault/config infrastructure tests

Run all:

npm test

Known Follow-up Work

The server behavior is Slack-specific, but some legacy skeleton assets remain intentionally preserved (Vault/Postgres flows and migration docs). If desired, those docs and compose defaults can be slimmed to a Slack-only deployment profile in a follow-up pass.