Slack Model Context Protocol Bridge

This is an advanced Model Context Protocol (MCP) intermediary service designed for seamless interaction with Slack Workspaces. It offers robust support for Stdio, SSE, and HTTP transfer modalities, configurable proxy settings, handling of Direct Messages (DMs) and Group DMs, intelligent message history fetching (based on time ranges or message counts), and can operate in two distinct modes: standard OAuth or a high-stealth mode requiring zero explicit permissions or scopes within the target Workspace 😏.

[!IMPORTANT]
Your continued engagement fuels this project's growth! With over 30,000 monthly engineer visits and 9,000 active users, your support is vital.

If you value the dedication of our contributors, please take a moment to bestow a star upon the repository.

This comprehensive Slack MCP Gateway boasts the following capabilities: - Stealth and OAuth Access Options: Deploy without needing subsequent application installations or permission grants (Stealth Mode), or utilize secure OAuth tokens to bypass the need for token extraction or manual refreshing (OAuth Mode). - Enterprise Grid Compatibility: Designed to integrate seamlessly with Enterprise Slack environments. - Channel and Thread Resolution with Aliases: Retrieve messages from specific channels and threads, supporting lookups by ID, channel name (e.g., #ops), and user DM handles (e.g., @support_user). - Intelligent History Retrieval: Fetch message sets using time-based windows (e.g., '7d', '1m') or by a fixed message quantity. - Message Query Functionality: Execute targeted searches across public channels, private channels, and direct conversations using temporal or content-based criteria. - Safeguarded Message Insertion: The conversations_add_message posting mechanism is deactivated by default for security. Activation requires setting an environmental flag, optionally restricted to a curated list of channel IDs. - DM and Group DM Access: Full capability to pull message data from one-on-one and multi-person direct conversations. - Contextual User Embedding: Augment returned message objects with essential user metadata. - Performance Caching: Implements local caching for user and channel metadata to expedite subsequent initialization and requests. - Transport Flexibility & Proxying: Compatible with any MCP client supporting Stdio, SSE, or HTTP, with integrated configuration for routing external traffic through a specified proxy server.

Analytics Demonstration

Message Posting Demonstration

Exposed Tools

1. conversations_history:

Retrieves message history for a specified conversation (channel or DM), using the final response cursor element for subsequent pagination calls. - Parameters: - channel_id (string, required): Identifier for the channel (format Cxxxxxxxxxx), or its human-readable identifier (e.g., #main or @user_dm). - include_activity_messages (boolean, default: false): Toggle to include system events like user joins/leaves in the output. - cursor (string, optional): Pagination token derived from the previous request's final response element. - limit (string, default: "1d"): Defines the fetch scope, either as a time duration (e.g., '1w', '90d') or a hard message count (e.g., "50"). This field must be omitted if cursor is supplied.

2. conversations_replies:

Fetches the message thread associated with a conversation ID and a specific parent message timestamp (thread_ts). Pagination is handled via a cursor in the final response element. - Parameters: - channel_id (string, required): The target conversation identifier (Cxxxxxxxxxx, #name, or @user_dm). - thread_ts (string, required): The unique timestamp (ts) of the initiating message in the format 1234567890.123456. - include_activity_messages (boolean, default: false): Controls the inclusion of system activity messages. - cursor (string, optional): Token for fetching the next batch of replies. - limit (string, default: "1d"): Specifies the fetch depth, either by time range or message count. Inactive when a cursor is present.

3. conversations_add_message

Allows for the insertion of a new message into a public channel, private channel, or direct message thread.

Security Advisory: Message submission is disabled by default. To activate, set the SLACK_MCP_ADD_MESSAGE_TOOL environment variable. Setting it to true enables posting universally; a comma-separated list of channel IDs permits whitelisting; prefixing with ! excludes specific channels. An empty value reverts to the default disabled state. Refer to the Environment Variables section below.

• Parameters:
• channel_id (string, required): Identifier for the destination conversation (ID, name, or DM handle).
• thread_ts (string, optional): The timestamp of the parent message if the content should be posted as a reply within an existing thread.
• payload (string, required): The content body of the message, formatted according to the specified content_type.
• content_type (string, default: "text/markdown"): Specifies the message formatting. Acceptable values are 'text/markdown' or 'text/plain'.

4. conversations_search_messages

Executes a targeted search across all accessible conversation types (public, private, DMs) using query parameters. If a URL is provided in search_query, it returns only the message at that URL, overriding all other filters. - Parameters: - search_query (string, optional): The search terms (e.g., 'project update') or a direct Slack message URL. Required if no other filters are set. - filter_in_channel (string, optional): Restrict search scope to a specific channel ID or name (e.g., #support). Defaults to all channels. - filter_in_im_or_mpim (string, optional): Restrict search scope to DMs or Group DMs by ID or user handle. - filter_users_with (string, optional): Limit results to messages where the specified user (ID or handle) was involved in the thread or DM. - filter_users_from (string, optional): Limit results to messages originated by the specified user (ID or handle). - filter_date_before (string, optional): Messages must have been sent prior to this date (e.g., '2023-12-31', 'Last Week'). - filter_date_after (string, optional): Messages must have been sent subsequent to this date (e.g., '2023-01-01', 'Yesterday'). - filter_date_on (string, optional): Filter for messages sent precisely on the specified date (e.g., '2024-01-15'). - filter_date_during (string, optional): Filter for messages sent within a specific period (e.g., 'Q4 2023'). - filter_threads_only (boolean, default: false): If true, only messages that are part of a thread (not the root message) are returned. - cursor (string, default: ""): Token for requesting the next result page. - limit (number, default: 20): Maximum number of results to return, constrained between 1 and 100.

5. channels_list:

Retrieves an index of all managed conversations within the workspace. - Parameters: - channel_types (string, required): A comma-separated enumeration of desired types: mpim, im, public_channel, private_channel. - sort (string, optional): Ordering criteria. Use popularity to sort by participant count. - limit (number, default: 100): The maximum cardinality of the returned list (max 999). - cursor (string, optional): Token to navigate to the next page of results.

Available Workspace Metadata Resources

The Slack Bridge Service exposes two specific directory URIs for immediate access to essential workspace metadata in CSV format:

1. slack://<workspace>/channels — Channel Directory Listing

Provides a comprehensive, comma-separated value inventory of all channel types (public, private, DM, group DM).

• URI: slack://<workspace>/channels
• Format: text/csv
• Data Fields:
• id: Unique Channel Identifier (e.g., C01A2B3C4D5)
• name: Channel Display Name (e.g., #announcements, @user_dm)
• topic: The channel's designated topic string (if set).
• purpose: The descriptive text defining the channel's goal.
• memberCount: Total active participants in the conversation.

2. slack://<workspace>/users — User Directory Listing

Returns a CSV index cataloging every user present in the workspace.

• URI: slack://<workspace>/users
• Format: text/csv
• Data Fields:
• userID: Internal User Identifier (e.g., U987X6Y5Z4W)
• userName: Slack system handle (e.g., jane.doe)
• realName: The user's officially registered full name.

Deployment Instructions

• Token Configuration
• Installation Procedures
• Runtime Configuration and Operation

Essential Environment Variables Quick Reference

Variable	Mandate?	Default Value	Purpose and Context
SLACK_MCP_XOXC_TOKEN	Required*	null	The primary browser session token (xoxc-...).
SLACK_MCP_XOXD_TOKEN	Required*	null	The session cookie token (xoxd-...), required alongside XOXC for certain authentication flows.
SLACK_MCP_XOXP_TOKEN	Required*	null	User OAuth token (xoxp-...); can substitute for the combination of xoxc/xoxd tokens.
SLACK_MCP_PORT	Optional	13080	The TCP port the bridge service will bind to for listening.
SLACK_MCP_HOST	Optional	127.0.0.1	The network interface IP address the service binds to.
SLACK_MCP_API_KEY	Optional	null	A secret bearer credential required for securing SSE and HTTP transport endpoints.
SLACK_MCP_PROXY	Optional	null	Specifies a full proxy URI to tunnel all outbound Slack API requests through.
SLACK_MCP_USER_AGENT	Optional	null	Permits overriding the default User-Agent string, crucial for some Enterprise setups.
SLACK_MCP_CUSTOM_TLS	Optional	null	Enables sending a customized TLS handshake signature, matching the configured SLACK_MCP_USER_AGENT or default settings, primarily for Enterprise environments.
SLACK_MCP_SERVER_CA	Optional	null	File path pointing to a custom Root Certificate Authority (.pem or .crt file).
SLACK_MCP_SERVER_CA_TOOLKIT	Optional	null	Instruction to inject the HTTPToolkit CA certificate into the system's trust store for Man-in-the-Middle inspection debugging.
SLACK_MCP_SERVER_CA_INSECURE	Optional	false	HIGHLY DISCOURAGED: Bypasses certificate validation for all outgoing requests.
SLACK_MCP_ADD_MESSAGE_TOOL	Optional	null	Controls message posting via conversations_add_message. Set to 'true' for global access, a channel ID list for specific access, or use '!' prefixed IDs for exclusion lists. Empty string disables the feature.
SLACK_MCP_ADD_MESSAGE_MARK	Optional	null	Automatically marks any newly posted message as 'read' within the conversation context upon successful delivery.
SLACK_MCP_ADD_MESSAGE_UNFURLING	Optional	null	When enabled, allows Slack to unfurl URLs in posted messages. Can be restricted by providing a domain whitelist (e.g., github.com,mycompany.org). Unfurling is blocked if the message contains whitelisted and non-whitelisted domains simultaneously, as a precaution.
SLACK_MCP_USERS_CACHE	Optional	.users_cache.json	Path to the JSON file used for persisting Slack user mapping data across restarts.
SLACK_MCP_CHANNELS_CACHE	Optional	.channels_cache_v2.json	Path to the JSON file used for persisting Slack channel mapping data across restarts.
SLACK_MCP_LOG_LEVEL	Optional	info	Sets the verbosity of output sent to standard output/error streams. Valid levels: debug, info, warn, error, panic, fatal.

*Authentication requires supplying the xoxp token OR both the xoxc AND xoxd tokens.

Feature Matrix and Cache Dependency

User Cache Present	Channel Cache Present	Operational Limitations
:x:	:x:	Full loss of persistent state. The channels_list tool will yield no results. Tools relying on resolution (e.g., conversations_*) will fail to resolve @handles or #names, limiting functionality exclusively to direct ID lookups.
:white_check_mark:	:x:	Channels listing via channels_list is non-functional. Resolving entities by name (like @userHandle or #channelName) in history retrieval or search operations will be unavailable, though ID-based calls remain functional.
:white_check_mark:	:white_check_mark:	Zero operational constraints. The service achieves maximum functionality across all provided tools and endpoints.

Debugging and Tracing Utilities

bash

Initiate the service interface using the local Stdio communication pipeline

npx @modelcontextprotocol/inspector go run mcp/mcp-server.go --transport stdio

Monitor detailed system logs

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Security Mandates

• Never distribute your authentication credentials or token strings.
• Ensure all configuration files (e.g., .env) are maintained under strict privacy controls.

Licensing Information

Protected under the MIT License; refer to the LICENSE file for full details. Note: This software is an independent implementation and is not officially affiliated with Slack.

WIKIPEDIA: XMLHttpRequest (XHR) represents a core browser API implemented as a JavaScript object, designed to facilitate asynchronous HTTP data exchange between a client-side script and a remote web server. Its methods allow web applications to initiate server requests post-initial page load and process incoming data. XHR is the foundational technology behind Ajax programming paradigms. Before its widespread adoption, server interaction predominantly relied on traditional page reloads triggered by form submissions or hyperlink navigation. The developers at Microsoft Outlook conceived the underlying concept in 2000, leading to its initial integration within Internet Explorer 5 (1999), albeit using legacy object identifiers like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), the standardized XMLHttpRequest identifier gained universal support across all major web rendering engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

== Standardization Trajectory == The World Wide Web Consortium (W3C) released the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by the Level 2 Working Draft on February 25, 2008, which introduced features like progress monitoring, cross-origin request facilitation, and byte stream handling. The Level 2 enhancements were later merged back into the primary specification by late 2011. Development responsibility transitioned to the WHATWG toward the end of 2012, which now maintains the living standard document utilizing Web IDL definitions.

== Operational Flow == Typical utilization of XMLHttpRequest involves a sequenced set of programmatic actions:

1. Instantiation: Creation of an XMLHttpRequest object instance.
2. Configuration: Invocation of the open() method to define the request method (GET, POST, etc.), target URI, and whether the operation should be synchronous or asynchronous.
3. Asynchronous Listener Setup: For non-blocking calls, a callback function must be assigned to monitor the object's state transitions.
4. Transmission: The request is dispatched by calling the send() method, optionally carrying data payload.
5. Response Handling: State changes are processed in the listener. Upon reaching state 4 ("done"), the complete server response is available, typically within the responseText property.

Beyond this core sequence, XHR provides advanced controls: custom headers can be set to guide server behavior; request payloads can be uploaded; responses can be parsed directly into JavaScript objects from formats like JSON, or processed incrementally as data streams arrive; and requests can be canceled or subjected to timeouts.

== Cross-Origin Communication Challenges ==

Early in the World Wide Web's evolution, limitations were identified regarding the ability to initiate requests across different security domains, often leading to the 'Same-Origin Policy' restrictions.