slack-search-mcp

This is an MCP server for searching Slack messages using the Model Context Protocol (MCP).

Overview

This server provides integration with Slack's search API using the Model Context Protocol (MCP). You can search for messages across your Slack workspace from MCP clients such as Claude Code or Continue.dev. The server filters and returns relevant message information including text, timestamps, users, and channel details.

Features

• get_slack_search_results: Search Slack messages using the Slack search.messages API
• Filtered Results: Returns only necessary message information (text, timestamp, user, channel, permalink)
• Pagination Support: Supports cursor-based pagination for large result sets
• Error Handling: Comprehensive error handling for authentication, permissions, and rate limiting
• Configurable: Supports configuration via config.json file

Slack App Configuration

1. Create an app at Slack API
2. Under OAuth & Permissions, add the following scopes:
   • search:read (required for searching messages)
3. Install the app to your workspace
4. Copy the User OAuth Token (starts with xoxp-)

Installation & Startup

1. Install uv

# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
iwr -useb https://astral.sh/uv/install.ps1 | iex

2. Project Setup

# Create a virtual environment
uv venv

# Activate the virtual environment
# Mac/Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

3. Set Environment Variables

Create a .env file in the project root and set the following variables:

SLACK_USER_TOKEN=xoxp-your-user-token
DEFAULT_SEARCH_COUNT=20

Important: Use a User OAuth Token (xoxp-) with search:read scope, not a Bot Token.

4. Optional Configuration

Create a config.json file for additional configuration:

{
  "slack": {
    "default_channels": ["general", "random"],
    "excluded_channels": [],
    "max_results_per_search": 100
  }
}

5. Using with MCP Clients

Configure your MCP client (e.g., Claude Code or Continue.dev) as follows:

{
  "mcpServers": {
    "slack-search": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "/path/to/slack-search-mcp"
    }
  }
}

To add the MCP server from the Claude Code command line:

claude mcp add slack-search uv run /path/to/slack-search-mcp/server.py

• slack-search: Server name (arbitrary)
• uv run ...: Starts the server with automatic virtual environment and dependency resolution

After running this command, slack-search will be added to the list of MCP servers in Claude Code, and the get_slack_search_results tool will be available.

Note: Since it is not possible to grant command permissions from Slack, it is recommended to run the server in a safe environment with auto-run or dangerously-skip-permissions mode enabled, so that the server does not prompt for command permissions.

6. Debugging

uv run mcp dev server.py

• Command: uv
• Arguments: run server.py

API Reference

get_slack_search_results

Searches for messages in your Slack workspace.

Parameters:

• query (string, required): Search query string
• count (integer, optional): Number of results to return (default: 20)
• cursor (string, optional): Pagination cursor for getting more results
• highlight (boolean, optional): Whether to highlight matching terms (default: true)

Returns:

{
  "messages": {
    "matches": [
      {
        "text": "Message content",
        "ts": "1234567890.123456",
        "permalink": "https://workspace.slack.com/archives/...",
        "user": "U1234567890",
        "username": "username",
        "channel": {
          "id": "C1234567890",
          "name": "channel-name"
        }
      }
    ],
    "total": 42,
    "pagination": {
      "next_cursor": "dGVhbTpDMH..."
    }
  }
}

Error Handling

The server handles various Slack API errors:

• Authentication errors: Invalid or missing token
• Permission errors: Missing search:read scope
• Rate limiting: Automatic handling of Slack API rate limits
• Network errors: SSL certificate and connection issues

Security Notes

• Store your Slack token securely in the .env file
• Never commit tokens to version control
• Use User OAuth tokens with minimal required scopes
• Consider using environment-specific tokens for different deployments