paymog__slack-cli/docs/03-configuration-and-usage.md

3. Configuration and Usage

You can configure the MCP server using command line arguments and environment variables.

Using DXT

For Claude Desktop users, you can use the DXT extension to run the MCP server without needing to edit the claude_desktop_config.json file directly. Download the latest version of the DXT Extension from releases page.

1. Open Claude Desktop and go to the Settings menu.
2. Click on the Extensions tab.
3. Drag and drop the downloaded .dxt file to install it and click "Install".
4. Fill all required configuration fields
   • Authentication method: xoxc/xoxd, xoxp, or xoxb.
   • Value for SLACK_MCP_XOXC_TOKEN and SLACK_MCP_XOXD_TOKEN in case of xoxc/xoxd method, SLACK_MCP_XOXP_TOKEN in case of xoxp, or SLACK_MCP_XOXB_TOKEN in case of xoxb.
   • You may also enable Add Message Tool to allow posting messages to channels.
   • You may also change User-Agent if needed if you have Enterprise Slack.
5. Enable MCP Server.

Important

You may need to disable bundled node in Claude Desktop and let it use node from host machine to avoid some startup issues in case you encounter them. It is DXT known bug: https://github.com/anthropics/dxt/issues/45#issuecomment-3050284228

Using Cursor Installer

The MCP server can be installed using the Cursor One-Click method.

Below are prepared configurations:

• npx and xoxc/xoxd method:
• npx and xoxp method:
• npx and xoxb method:

Important

Remember to replace tokens in the configuration with your own tokens, as they are just examples.

Using npx

If you have npm installed, this is the fastest way to get started with slack-mcp-server on Claude Desktop.

Open your claude_desktop_config.json and add the mcp server to the list of mcpServers:

Warning

If you are using Enterprise Slack, you may set SLACK_MCP_USER_AGENT environment variable to match your browser's User-Agent string from where you extracted xoxc and xoxd and enable SLACK_MCP_CUSTOM_TLS to enable custom TLS-handshakes to start to look like a real browser. This is required for the server to work properly in some environments with higher security policies.

Option 1: Using XOXP Token

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "slack-mcp-server@latest",
        "--transport",
        "stdio"
      ],
      "env": {
        "SLACK_MCP_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

Option 2: Using XOXB Token (Bot)

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "slack-mcp-server@latest",
        "--transport",
        "stdio"
      ],
      "env": {
        "SLACK_MCP_XOXB_TOKEN": "xoxb-..."
      }
    }
  }
}

Option 3: Using XOXC/XOXD Tokens

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "slack-mcp-server@latest",
        "--transport",
        "stdio"
      ],
      "env": {
        "SLACK_MCP_XOXC_TOKEN": "xoxc-...",
        "SLACK_MCP_XOXD_TOKEN": "xoxd-..."
      }
    }
  }
}

Or, stdio transport with docker.

Option 1: Using XOXP Token

{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SLACK_MCP_XOXP_TOKEN",
        "ghcr.io/korotovsky/slack-mcp-server",
        "--transport",
        "stdio"
      ],
      "env": {
        "SLACK_MCP_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

Option 2: Using XOXC/XOXD Tokens

{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SLACK_MCP_XOXC_TOKEN",
        "-e",
        "SLACK_MCP_XOXD_TOKEN",
        "ghcr.io/korotovsky/slack-mcp-server",
        "--transport",
        "stdio"
      ],
      "env": {
        "SLACK_MCP_XOXC_TOKEN": "xoxc-...",
        "SLACK_MCP_XOXD_TOKEN": "xoxd-..."
      }
    }
  }
}

Please see Docker for more information.

Using npx with sse transport:

In case you would like to run it in sse mode, then you should use mcp-remote wrapper for Claude Desktop and deploy/expose MCP server somewhere e.g. with ngrok or docker-compose.

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://x.y.z.q:3001/sse",
        "--header",
        "Authorization: Bearer ${SLACK_MCP_API_KEY}"
      ],
      "env": {
        "SLACK_MCP_API_KEY": "my-$$e-$ecret"
      }
    }
  }
}

Or, sse transport for Windows.

{
  "mcpServers": {
    "slack": {
      "command": "C:\\Progra~1\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "mcp-remote",
        "https://x.y.z.q:3001/sse",
        "--header",
        "Authorization: Bearer ${SLACK_MCP_API_KEY}"
      ],
      "env": {
        "SLACK_MCP_API_KEY": "my-$$e-$ecret"
      }
    }
  }
}

TLS and Exposing to the Internet

There are several reasons why you might need to setup HTTPS for your SSE.

• mcp-remote is capable to handle only https schemes;
• it is generally a good practice to use TLS for any service exposed to the internet;

You could use ngrok:

ngrok http 3001

and then use the endpoint https://903d-xxx-xxxx-xxxx-10b4.ngrok-free.app for your mcp-remote argument.

Using Docker

For detailed information about all environment variables, see Environment Variables.

export SLACK_MCP_XOXC_TOKEN=xoxc-...
export SLACK_MCP_XOXD_TOKEN=xoxd-...

docker pull ghcr.io/korotovsky/slack-mcp-server:latest
docker run -i --rm \
  -e SLACK_MCP_XOXC_TOKEN \
  -e SLACK_MCP_XOXD_TOKEN \
  ghcr.io/korotovsky/slack-mcp-server:latest --transport stdio

Or, the docker-compose way:

wget -O docker-compose.yml https://github.com/korotovsky/slack-mcp-server/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/korotovsky/slack-mcp-server/releases/latest/download/default.env.dist
nano .env # Edit .env file with your tokens from step 1 of the setup guide
docker network create app-tier
docker-compose up -d

Console Arguments

Argument	Required ?	Description
--transport or -t	Yes	Select transport for the MCP Server, possible values are: stdio, sse
--enabled-tools or -e	No	Comma-separated list of tools to register. If not set, all tools are registered. Runtime permissions (e.g., SLACK_MCP_ADD_MESSAGE_TOOL) are still enforced. Available tools: conversations_history, conversations_replies, conversations_add_message, reactions_add, reactions_remove, attachment_get_data, conversations_search_messages, conversations_join, conversations_leave, conversations_unreads, conversations_mark, channels_list, channels_me, usergroups_list, usergroups_me, usergroups_create, usergroups_update, usergroups_users_update, users_search.

Environment Variables

Variable	Required?	Default	Description
SLACK_MCP_XOXC_TOKEN	Yes*	nil	Slack browser token (xoxc-...)
SLACK_MCP_XOXD_TOKEN	Yes*	nil	Slack browser cookie d (xoxd-...)
SLACK_MCP_XOXP_TOKEN	Yes*	nil	User OAuth token (xoxp-...) — alternative to xoxc/xoxd
SLACK_MCP_PORT	No	13080	Port for the MCP server to listen on
SLACK_MCP_HOST	No	127.0.0.1	Host for the MCP server to listen on
SLACK_MCP_API_KEY	No	nil	Bearer token for SSE and HTTP transports
SLACK_MCP_PROXY	No	nil	Proxy URL for outgoing requests
SLACK_MCP_USER_AGENT	No	nil	Custom User-Agent (for Enterprise Slack environments)
SLACK_MCP_CUSTOM_TLS	No	nil	Send custom TLS-handshake to Slack servers based on SLACK_MCP_USER_AGENT or default User-Agent. (for Enterprise Slack environments)
SLACK_MCP_SERVER_CA	No	nil	Path to CA certificate
SLACK_MCP_SERVER_CA_TOOLKIT	No	nil	Inject HTTPToolkit CA certificate to root trust-store for MitM debugging
SLACK_MCP_SERVER_CA_INSECURE	No	false	Trust all insecure requests (NOT RECOMMENDED)
SLACK_MCP_ADD_MESSAGE_TOOL	No	nil	Enable message posting via conversations_add_message by setting it to true for all channels, a comma-separated list of channel IDs to whitelist specific channels, or use ! before a channel ID to allow all except specified ones. If empty, the tool is only registered when explicitly listed in SLACK_MCP_ENABLED_TOOLS.
SLACK_MCP_ADD_MESSAGE_MARK	No	nil	When conversations_add_message is enabled (via SLACK_MCP_ADD_MESSAGE_TOOL or SLACK_MCP_ENABLED_TOOLS), setting this to true will automatically mark sent messages as read.
SLACK_MCP_ADD_MESSAGE_UNFURLING	No	nil	Enable to let Slack unfurl posted links or set comma-separated list of domains e.g. github.com,slack.com to whitelist unfurling only for them. If text contains whitelisted and unknown domain unfurling will be disabled for security reasons.
SLACK_MCP_USERS_CACHE	No	.users_cache.json	Path to the users cache file. Used to cache Slack user information to avoid repeated API calls on startup.
SLACK_MCP_CHANNELS_CACHE	No	.channels_cache_v2.json	Path to the channels cache file. Used to cache Slack channel information to avoid repeated API calls on startup.
SLACK_MCP_CACHE_TTL	No	24h	Cache time-to-live. Supports duration format (24h, 30m) or seconds (3600). Set to 0 to disable TTL (cache forever). When the cache expires, stale data is served immediately while a background refresh fetches fresh data.
SLACK_MCP_MIN_REFRESH_INTERVAL	No	30s	Minimum interval between forced cache refreshes. Prevents API abuse from repeated force-refresh requests. Supports duration format (30s, 1m) or seconds (60). Set to 0 to disable rate limiting.
SLACK_MCP_LOG_LEVEL	No	info	Log-level for stdout or stderr. Valid values are: debug, info, warn, error, panic and fatal
SLACK_MCP_ENABLED_TOOLS	No	nil	Comma-separated list of tools to register. If empty, all read-only tools and usergroups tools are registered; write tools (conversations_add_message, reactions_add, reactions_remove, attachment_get_data) require their specific env var to be set OR must be explicitly listed here. When a write tool is listed here, it's enabled without channel restrictions. Available tools: conversations_history, conversations_replies, conversations_add_message, reactions_add, reactions_remove, attachment_get_data, conversations_search_messages, conversations_join, conversations_leave, conversations_unreads, conversations_mark, channels_list, channels_me, usergroups_list, usergroups_me, usergroups_create, usergroups_update, usergroups_users_update, users_search.

Tool Registration and Permissions

Overview

Tools are controlled at two levels:

• Registration (SLACK_MCP_ENABLED_TOOLS) — determines which tools are visible to MCP clients
• Runtime permissions (tool-specific env vars like SLACK_MCP_ADD_MESSAGE_TOOL) — channel restrictions for write tools

Write tools (conversations_add_message, reactions_add, reactions_remove, attachment_get_data) are not registered by default to prevent accidental exposure. To enable them, you must either:

1. Set their specific environment variable (e.g., SLACK_MCP_ADD_MESSAGE_TOOL), or
2. Explicitly list them in SLACK_MCP_ENABLED_TOOLS

Usergroups tools (usergroups_list, usergroups_me, usergroups_create, usergroups_update, usergroups_users_update) are registered by default. They require appropriate OAuth scopes (usergroups:read for read operations, usergroups:write for write operations).

Examples

Example 1: Read-only mode (default)

By default, only read-only tools are available. No write tools are registered.

{
  "env": {
    "SLACK_MCP_XOXP_TOKEN": "xoxp-..."
  }
}

Example 2: Enable messaging to specific channels

Use SLACK_MCP_ADD_MESSAGE_TOOL to enable messaging with channel restrictions:

{
  "env": {
    "SLACK_MCP_XOXP_TOKEN": "xoxp-...",
    "SLACK_MCP_ADD_MESSAGE_TOOL": "C123456789,C987654321"
  }
}

Example 3: Enable messaging without channel restrictions

Use SLACK_MCP_ENABLED_TOOLS to register write tools without restrictions:

{
  "env": {
    "SLACK_MCP_XOXP_TOKEN": "xoxp-...",
    "SLACK_MCP_ENABLED_TOOLS": "conversations_history,conversations_add_message,reactions_add"
  }
}

Example 4: Minimal read-only setup

Expose only specific tools:

{
  "env": {
    "SLACK_MCP_XOXP_TOKEN": "xoxp-...",
    "SLACK_MCP_ENABLED_TOOLS": "channels_list,conversations_history"
  }
}

Behavior Matrix

ENABLED_TOOLS	Tool-specific env var	Write tool registered?	Channel restrictions
empty/not set	not set	No	N/A
empty/not set	true	Yes	None
empty/not set	C123,C456	Yes	Only listed channels
includes tool	not set	Yes	None
includes tool	C123,C456	Yes	Only listed channels
excludes tool	any	No	N/A