@kazuph/mcp-slack 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dmitrii Korotovskii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Slack MCP Server
+
+Model Context Protocol (MCP) server for Slack Workspaces. The most powerful MCP Slack server — supports Stdio and SSE transports, proxy settings, DMs, Group DMs, Smart History fetch (by date or count), may work via OAuth or in complete stealth mode with no permissions and scopes in Workspace 😏.
+
+> [!IMPORTANT]  
+> We need your support! Each month, over 30,000 engineers visit this repository, and more than 9,000 are already using it.
+> 
+> If you appreciate the work our [contributors](https://github.com/korotovsky/slack-mcp-server/graphs/contributors) have put into this project, please consider giving the repository a star.
+
+This feature-rich Slack MCP Server has:
+- **Stealth and OAuth Modes**: Run the server without requiring additional permissions or bot installations (stealth mode), or use secure OAuth tokens for access without needing to refresh or extract tokens from the browser (OAuth mode).
+- **Enterprise Workspaces Support**: Possibility to integrate with Enterprise Slack setups.
+- **Channel and Thread Support with `#Name` `@Lookup`**: Fetch messages from channels and threads, including activity messages, and retrieve channels using their names (e.g., #general) as well as their IDs. Enhanced user lookup with display name and real name fallback (v1.2.0).
+- **Smart History**: Fetch messages with pagination by date (d1, 7d, 1m) or message count.
+- **Search Messages**: Search messages in channels, threads, and DMs using various filters like date, user, and content.
+- **Safe Message Posting**: The `conversations_add_message` tool is disabled by default for safety. Enable it via an environment variable, with optional channel restrictions.
+- **Channel Management**: Create and rename public channels, invite users, and set topics (new in v1.1.20).
+- **Advanced User Resolution**: Resolve users by username, display name, real name, or email with Unicode normalization support for invisible characters (new in v1.2.0).
+- **DM and Group DM support**: Retrieve direct messages and group direct messages.
+- **Embedded user information**: Embed user information in messages, for better context.
+- **Cache support**: Cache users and channels for faster access.
+- **Stdio/SSE Transports & Proxy Support**: Use the server with any MCP client that supports Stdio or SSE transports, and configure it to route outgoing requests through a proxy if needed.
+
+### Analytics Demo
+
+![Analytics](images/feature-1.gif)
+
+### Add Message Demo
+
+![Add Message](images/feature-2.gif)
+
+## Tools
+
+### 1. conversations_history:
+Get messages from the channel (or DM) by channel_id, the last row/column in the response is used as 'cursor' parameter for pagination if not empty
+- **Parameters:**
+  - `channel_id` (string, required):     - `channel_id` (string): ID of the channel in format Cxxxxxxxxxx or its name starting with `#...` or `@...` aka `#general` or `@username_dm`.
+  - `include_activity_messages` (boolean, default: false): If true, the response will include activity messages such as `channel_join` or `channel_leave`. Default is boolean false.
+  - `cursor` (string, optional): Cursor for pagination. Use the value of the last row and column in the response as next_cursor field returned from the previous request.
+  - `limit` (string, default: "1d"): Limit of messages to fetch in format of maximum ranges of time (e.g. 1d - 1 day, 30d - 30 days, 90d - 90 days which is a default limit for free tier history) or number of messages (e.g. 50). Must be empty when 'cursor' is provided.
+
+### 2. conversations_replies:
+Get a thread of messages posted to a conversation by channelID and `thread_ts`, the last row/column in the response is used as `cursor` parameter for pagination if not empty.
+- **Parameters:**
+  - `channel_id` (string, required): ID of the channel in format `Cxxxxxxxxxx` or its name starting with `#...` or `@...` aka `#general` or `@username_dm`.
+  - `thread_ts` (string, required): Unique identifier of either a thread’s parent message or a message in the thread. ts must be the timestamp in format `1234567890.123456` of an existing message with 0 or more replies.
+  - `include_activity_messages` (boolean, default: false): If true, the response will include activity messages such as 'channel_join' or 'channel_leave'. Default is boolean false.
+  - `cursor` (string, optional): Cursor for pagination. Use the value of the last row and column in the response as next_cursor field returned from the previous request.
+  - `limit` (string, default: "1d"): Limit of messages to fetch in format of maximum ranges of time (e.g. 1d - 1 day, 30d - 30 days, 90d - 90 days which is a default limit for free tier history) or number of messages (e.g. 50). Must be empty when 'cursor' is provided.
+
+### 3. conversations_add_message
+Add a message to a public channel, private channel, or direct message (DM, or IM) conversation by channel_id and thread_ts.
+
+> **Note:** Posting messages is disabled by default for safety. To enable, set the `SLACK_MCP_ADD_MESSAGE_TOOL` environment variable. If set to a comma-separated list of channel IDs, posting is enabled only for those specific channels. See the Environment Variables section below for details.
+
+- **Parameters:**
+  - `channel_id` (string, required): ID of the channel in format `Cxxxxxxxxxx` or its name starting with `#...` or `@...` aka `#general` or `@username_dm`.
+  - `thread_ts` (string, optional): Unique identifier of either a thread’s parent message or a message in the thread_ts must be the timestamp in format `1234567890.123456` of an existing message with 0 or more replies. Optional, if not provided the message will be added to the channel itself, otherwise it will be added to the thread.
+  - `payload` (string, required): Message payload in specified content_type format. Example: 'Hello, world!' for text/plain or '# Hello, world!' for text/markdown.
+  - `content_type` (string, default: "text/markdown"): Content type of the message. Default is 'text/markdown'. Allowed values: 'text/markdown', 'text/plain'.
+
+### 4. conversations_search_messages
+Search messages in a public channel, private channel, or direct message (DM, or IM) conversation using filters. All filters are optional, if not provided then search_query is required.
+- **Parameters:**
+  - `search_query` (string, optional): Search query to filter messages. Example: `marketing report`.
+  - `filter_in_channel` (string, optional): Filter messages in a specific channel by its ID or name. Example: `C1234567890` or `#general`. If not provided, all channels will be searched.
+  - `filter_in_im_or_mpim` (string, optional): Filter messages in a direct message (DM) or multi-person direct message (MPIM) conversation by its ID or name. Example: `D1234567890` or `@username_dm`. If not provided, all DMs and MPIMs will be searched.
+  - `filter_users_with` (string, optional): Filter messages with a specific user by their ID or display name in threads and DMs. Example: `U1234567890` or `@username`. If not provided, all threads and DMs will be searched.
+  - `filter_users_from` (string, optional): Filter messages from a specific user by their ID or display name. Example: `U1234567890` or `@username`. If not provided, all users will be searched.
+  - `filter_date_before` (string, optional): Filter messages sent before a specific date in format `YYYY-MM-DD`. Example: `2023-10-01`, `July`, `Yesterday` or `Today`. If not provided, all dates will be searched.
+  - `filter_date_after` (string, optional): Filter messages sent after a specific date in format `YYYY-MM-DD`. Example: `2023-10-01`, `July`, `Yesterday` or `Today`. If not provided, all dates will be searched.
+  - `filter_date_on` (string, optional): Filter messages sent on a specific date in format `YYYY-MM-DD`. Example: `2023-10-01`, `July`, `Yesterday` or `Today`. If not provided, all dates will be searched.
+  - `filter_date_during` (string, optional): Filter messages sent during a specific period in format `YYYY-MM-DD`. Example: `July`, `Yesterday` or `Today`. If not provided, all dates will be searched.
+  - `filter_threads_only` (boolean, default: false): If true, the response will include only messages from threads. Default is boolean false.
+  - `cursor` (string, default: ""): Cursor for pagination. Use the value of the last row and column in the response as next_cursor field returned from the previous request.
+  - `limit` (number, default: 20): The maximum number of items to return. Must be an integer between 1 and 100.
+
+### 5. channels_list:
+Get list of channels
+- **Parameters:**
+  - `channel_types` (string, required): Comma-separated channel types. Allowed values: `mpim`, `im`, `public_channel`, `private_channel`. Example: `public_channel,private_channel,im`
+  - `sort` (string, optional): Type of sorting. Allowed values: `popularity` - sort by number of members/participants in each channel.
+  - `limit` (number, default: 100): The maximum number of items to return. Must be an integer between 1 and 1000 (maximum 999).
+  - `cursor` (string, optional): Cursor for pagination. Use the value of the last row and column in the response as next_cursor field returned from the previous request.
+
+### 6. conversations_create:
+Create a new public channel
+- **Parameters:**
+  - `name` (string, required): Name of the channel to create. Must be 80 characters or less.
+
+### 7. conversations_rename:
+Rename a public channel
+- **Parameters:**
+  - `channel_id` (string, required): ID of the channel to rename in format `Cxxxxxxxxxx` or its name starting with `#...` aka `#general`
+  - `name` (string, required): New name for the channel. Must be 80 characters or less.
+
+### 8. conversations_invite:
+Invite users to a public channel
+- **Parameters:**
+  - `channel_id` (string, required): ID of the channel in format `Cxxxxxxxxxx` or its name starting with `#...` aka `#general`
+  - `users` (string, required): Comma-separated list of user IDs (U1234567890) or usernames (@username) to invite
+
+### 9. conversations_set_topic:
+Set the topic/description of a public channel
+- **Parameters:**
+  - `channel_id` (string, required): ID of the channel in format `Cxxxxxxxxxx` or its name starting with `#...` aka `#general`
+  - `topic` (string, required): New topic/description for the channel
+
+### 10. users_resolve:
+Resolve a user by their username, display name, real name, or email with Unicode normalization support. This tool handles invisible characters (zero-width spaces) that may appear in user names and automatically falls back to real name when display name is empty.
+- **Parameters:**
+  - `query` (string, required): The search query (username, display name, real name, or email). Can start with @ but it's not required. Supports Unicode normalization for invisible characters.
+  - `search_type` (string, optional, default: `auto`): Type of search to perform. Options:
+    - `username`: Search by Slack username only
+    - `display_name`: Search by display name (falls back to real name if display name is empty)
+    - `real_name`: Search by real name only  
+    - `email`: Search by email address only
+    - `auto`: Searches all fields with priority: username exact → display name exact → real name exact → email exact → partial matches
+- **Returns:** CSV format with user information including userID, userName, realName, displayName, email, matchType, and isBot status
+
+**Note:** User resolution improvements in v1.2.0 also enhance the `conversations_invite` and `conversations_add_message` tools, which now support user lookup by display name and real name in addition to username.
+
+## Setup Guide
+
+- [Authentication Setup](docs/01-authentication-setup.md)
+- [Installation](docs/02-installation.md)
+- [Configuration and Usage](docs/03-configuration-and-usage.md)
+
+### Environment Variables (Quick Reference)
+
+| 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_SSE_API_KEY`        | No        | `nil`                     | Bearer token for SSE transport                                                                                                                                                                                                                                                            |
+| `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_SERVER_CA`          | No        | `nil`                     | Path to CA certificate                                                                                                                                                                                                                                                                    |
+| `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, while an empty value disables posting by default. |
+| `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.                                                                                                                                                                          |
+
+*You need either `xoxp` **or** both `xoxc`/`xoxd` tokens for authentication.
+
+### Debugging Tools
+
+```bash
+# Run the inspector with stdio transport
+npx @modelcontextprotocol/inspector go run mcp/mcp-server.go --transport stdio
+
+# View logs
+tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
+```
+
+## Security
+
+- Never share API tokens
+- Keep .env files secure and private
+
+## License
+
+Licensed under MIT - see [LICENSE](LICENSE) file. This is not an official Slack product.

package/bin/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const childProcess = require('child_process');
+
+const BINARY_MAP = {
+    darwin_x64:   { name: '@kazuph/mcp-slack-darwin-amd64',    binaryName: 'slack-mcp-server-darwin-amd64',    suffix: '' },
+    darwin_arm64: { name: '@kazuph/mcp-slack-darwin-arm64',    binaryName: 'slack-mcp-server-darwin-arm64',    suffix: '' },
+    linux_x64:    { name: '@kazuph/mcp-slack-linux-amd64',     binaryName: 'slack-mcp-server-linux-amd64',     suffix: '' },
+    linux_arm64:  { name: '@kazuph/mcp-slack-linux-arm64',     binaryName: 'slack-mcp-server-linux-arm64',     suffix: '' },
+    win32_x64:    { name: '@kazuph/mcp-slack-windows-amd64',   binaryName: 'slack-mcp-server-windows-amd64',   suffix: '.exe' },
+    win32_arm64:  { name: '@kazuph/mcp-slack-windows-arm64',   binaryName: 'slack-mcp-server-windows-arm64',   suffix: '.exe' },
+};
+
+function resolveBinaryPath() {
+    // If DXT installation then we fix empty variables, it's a DXT bug.
+    if (process.env.SLACK_MCP_DXT) {
+        if (process.env.SLACK_MCP_XOXC_TOKEN === '${user_config.xoxc_token}') {
+            process.env.SLACK_MCP_XOXC_TOKEN = '';
+        }
+        if (process.env.SLACK_MCP_XOXD_TOKEN === '${user_config.xoxd_token}') {
+            process.env.SLACK_MCP_XOXD_TOKEN = '';
+        }
+        if (process.env.SLACK_MCP_XOXP_TOKEN === '${user_config.xoxp_token}') {
+            process.env.SLACK_MCP_XOXP_TOKEN = '';
+        }
+        if (process.env.SLACK_MCP_ADD_MESSAGE_TOOL === '${user_config.add_message_tool}') {
+            process.env.SLACK_MCP_ADD_MESSAGE_TOOL = '';
+        }
+    }
+
+    const key = `${process.platform}_${process.arch}`;
+    const binary = BINARY_MAP[key];
+    if (!binary) {
+        throw new Error(`Could not resolve binary for platform/arch: ${process.platform}/${process.arch}`);
+    }
+
+    if (process.env.SLACK_MCP_DXT) {
+        return require.resolve(path.join(__dirname, `${binary.binaryName}${binary.suffix}`));
+    } else {
+        return require.resolve(`${binary.name}/bin/${binary.binaryName}${binary.suffix}`);
+    }
+}
+
+const binPath = resolveBinaryPath();
+
+// Workaround for https://github.com/anthropics/dxt/issues/13
+if (process.env.SLACK_MCP_DXT) {
+    const stats = fs.statSync(binPath);
+    const execMask = fs.constants.S_IXUSR
+        | fs.constants.S_IXGRP
+        | fs.constants.S_IXOTH;
+
+    if ((stats.mode & execMask) !== execMask) {
+        const newMode = stats.mode | execMask;
+        fs.chmodSync(binPath, newMode);
+    }
+}
+
+childProcess.execFileSync(binPath, process.argv.slice(2), {
+    stdio: 'inherit',
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kazuph/mcp-slack",
+  "version": "1.2.0",
+  "description": "Model Context Protocol (MCP) server for Slack Workspaces. This integration supports both Stdio and SSE transports, proxy settings and does not require any permissions or bots being created or approved by Workspace admins",
+  "main": "bin/index.js",
+  "bin": {
+    "mcp-slack": "bin/index.js"
+  },
+  "optionalDependencies": {
+    "@kazuph/mcp-slack-darwin-amd64": "1.2.0",
+    "@kazuph/mcp-slack-darwin-arm64": "1.2.0",
+    "@kazuph/mcp-slack-linux-amd64": "1.2.0",
+    "@kazuph/mcp-slack-linux-arm64": "1.2.0",
+    "@kazuph/mcp-slack-windows-amd64": "1.2.0",
+    "@kazuph/mcp-slack-windows-arm64": "1.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazuph/mcp-slack.git"
+  },
+  "keywords": [
+    "mcp",
+    "slack",
+    "slack-api",
+    "model context protocol",
+    "model",
+    "context",
+    "protocol"
+  ],
+  "author": {
+    "name": "kazuph",
+    "url": "https://github.com/kazuph"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kazuph/mcp-slack/issues"
+  },
+  "homepage": "https://github.com/kazuph/mcp-slack#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}