npm package: @nlile/server-slack-advanced
Description: Slack MCP server with private and public-channel support
Author: nlile
Latest version: 0.0.6

# Slack MCP Server (Advanced)

MCP Server for the Slack API, enabling Claude to interact with Slack workspaces, including private channels.

## Tools

1.  `slack_list_channels`
    -   List public, private (if bot is invited), or pre-defined channels in the workspace.
    -   Optional inputs:
        -   `limit` (number, default: 100, max: 200): Maximum number of channels to return
        -   `cursor` (string): Pagination cursor for next page
    -   Returns: List of channels with their IDs and information

2.  `slack_post_message`
    -   Post a new message to a Slack channel
    -   Required inputs:
        -   `channel_id` (string): The ID of the channel to post to
        -   `text` (string): The message text to post
    -   Optional inputs (requires `chat:write.customize` scope):
        -   `username` (string): Custom display name for this message
        -   `icon_url` (string): URL to an image to use as the avatar
        -   `icon_emoji` (string): Emoji code (like `:robot_face:`) to use as the avatar
    -   Returns: Message posting confirmation and timestamp

3.  `slack_reply_to_thread`
    -   Reply to a specific message thread
    -   Required inputs:
        -   `channel_id` (string): The channel containing the thread
        -   `thread_ts` (string): Timestamp of the parent message
        -   `text` (string): The reply text
    -   Optional inputs (requires `chat:write.customize` scope):
        -   `username` (string): Custom display name for this message
        -   `icon_url` (string): URL to an image to use as the avatar
        -   `icon_emoji` (string): Emoji code (like `:robot_face:`) to use as the avatar
    -   Returns: Reply confirmation and timestamp

4.  `slack_add_reaction`
    -   Add an emoji reaction to a message
    -   Required inputs:
        -   `channel_id` (string): The channel containing the message
        -   `timestamp` (string): Message timestamp to react to
        -   `reaction` (string): Emoji name without colons
    -   Returns: Reaction confirmation

5.  `slack_get_channel_history`
    -   Get recent messages from a channel
    -   Required inputs:
        -   `channel_id` (string): The channel ID
    -   Optional inputs:
        -   `limit` (number, default: 10): Number of messages to retrieve
    -   Returns: List of messages with their content and metadata

6.  `slack_get_thread_replies`
    -   Get all replies in a message thread
    -   Required inputs:
        -   `channel_id` (string): The channel containing the thread
        -   `thread_ts` (string): Timestamp of the parent message
    -   Returns: List of replies with their content and metadata


7.  `slack_get_users`
    -   Get list of workspace users with basic profile information
    -   Optional inputs:
        -   `cursor` (string): Pagination cursor for next page
        -   `limit` (number, default: 100, max: 200): Maximum users to return
    -   Returns: List of users with their basic profiles

8.  `slack_get_user_profile`
    -   Get detailed profile information for a specific user
    -   Required inputs:
        -   `user_id` (string): The user's ID
    -   Returns: Detailed user profile information

9.  `slack_edit_message`
    -   Edit an existing message posted by the bot
    -   Required inputs:
        -   `channel_id` (string): The ID of the channel containing the message
        -   `ts` (string): Timestamp of the message to edit
        -   `text` (string): The new text for the message
    -   Optional inputs (requires `chat:write.customize` scope):
        -   `username` (string): Custom display name for this message
        -   `icon_url` (string): URL to an image to use as the avatar
        -   `icon_emoji` (string): Emoji code (like `:robot_face:`) to use as the avatar
    -   Returns: Message update confirmation

## Setup

1.  Create a Slack App:
    -   Visit the [Slack Apps page](https://api.slack.com/apps)
    -   Click "Create New App"
    -   Choose "From scratch"
    -   Name your app and select your workspace

2.  Configure Bot Token Scopes:
    Navigate to "OAuth & Permissions" and add these scopes:
    -   `channels:history` - View messages and other content in public channels
    -   `channels:read` - View basic public channel information
    -   `groups:read` - View basic private channel information (needed for `slack_list_channels`)
    -   `chat:write` - Send messages as the app
    -   `chat:write.customize` - Send messages with a custom username and avatar
    -   `reactions:write` - Add emoji reactions to messages
    -   `users:read` - View users and their basic information
    -   `users.profile:read` - View user profile details (needed for `slack_get_user_profile`)

3.  Install App to Workspace:
    -   Click "Install to Workspace" and authorize the app
    -   Save the "Bot User OAuth Token" that starts with `xoxb-`

4.  Get your Team ID (starts with a `T`) by following [this guidance](https://slack.com/help/articles/221769328-Locate-your-Slack-URL-or-ID#find-your-workspace-or-org-id)

### Usage with Claude Desktop

Add the following to your `claude_desktop_config.json`:

#### npx

```json
{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "@nlile/server-slack-advanced"
      ],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
        "SLACK_TEAM_ID": "T01234567",
        "SLACK_CHANNEL_IDS": "C01234567,G76543210"
      }
    }
  }
}
```

#### docker

```json
{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SLACK_BOT_TOKEN",
        "-e",
        "SLACK_TEAM_ID",
        "-e",
        "SLACK_CHANNEL_IDS",
        "nlile/server-slack-advanced" // update image name if you build it
      ],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
        "SLACK_TEAM_ID": "T01234567",
        "SLACK_CHANNEL_IDS": "C01234567,G76543210" // can be public (C...) or private (G...)
      }
    }
  }
}
```

### Environment Variables

1.  `SLACK_BOT_TOKEN`: Required. The Bot User OAuth Token starting with `xoxb-`.
2.  `SLACK_TEAM_ID`: Required for listing all channels or users. Your Slack workspace ID starting with `T`.
3.  `SLACK_CHANNEL_IDS`: Optional. Comma-separated list of specific channel IDs (public `C...` or private `G...`) to limit access to. If set, only these channels will be visible/accessible via the tools. If not set, `slack_list_channels` will list all public channels and private channels the bot has been invited to (requires `groups:read` scope). The bot must be explicitly invited to any private channels it needs to interact with, regardless of this setting.

### Troubleshooting

If you encounter permission errors, verify that:
1.  All required scopes (including `groups:read` for private channels) are added to your Slack app.
2.  The app is properly installed/reinstalled to your workspace after scope changes.
3.  The tokens and workspace ID are correctly copied to your configuration.
4.  The app has been added (`/invite @YourBotName`) to the specific private channels it needs to access.

## Build

Docker build:

```bash
# update tag as needed
docker build -t nlile/server-slack-advanced:latest -f src/slack/Dockerfile .
```

## Testing Locally

1.  **Build the code:** `npm run build --workspace src/slack`
2.  **Pack the package:** `cd src/slack && npm pack`
    - This creates a `.tgz` file (e.g., `nlile-server-slack-advanced-0.0.3.tgz`).
3.  **Install globally (for testing):** e.g. `npm install -g nlile-server-slack-advanced-0.0.{x}.tgz`
4.  **Run the server:**
    ```bash
    export SLACK_BOT_TOKEN="your-token"
    export SLACK_TEAM_ID="your-team-id"
    mcp-server-slack-advanced
    ```
5.  **Test with an MCP client** (like Claude Desktop or a script) to ensure it connects and tools work.
6.  **Uninstall:** `npm uninstall -g @nlile/server-slack-advanced`

## Publishing to NPM

1.  **Ensure clean git status:** `git status` (commit or stash changes).
2.  **Login to npm:** `npm login` (if not already logged in).
3.  **Bump version:** `cd src/slack && npm version patch` (or `minor`/`major`). This updates `package.json` and creates a git commit/tag.
4.  **Push git changes:** `git push && git push --tags`
5.  **Publish:** `cd src/slack && npm publish --access public` (use `--access public` for scoped packages on the free tier).

## License

This MCP server is licensed under the MIT License.