Tarantella MCPs - Slack MCP Server

A Model Context Protocol (MCP) server implementation that provides Slack search capabilities to Claude and other MCP clients.

Overview

This MCP server enables AI assistants to search Slack messages and channels using the Slack Web API. It provides two main tools:

• search-messages: Search across all accessible Slack messages

• search-in-channel: Search within a specific Slack channel

Prerequisites

• Node.js v22 or later (see .nvmrc)

• A Slack workspace with API access

• A Slack Bot Token with appropriate permissions

Slack Setup

1. Create a Slack App

1. Go to https://api.slack.com/apps

2. Click "Create New App" and choose "From scratch"

3. Give your app a name (e.g., "MCP Search Bot") and select your workspace

4. Click "Create App"

2. Configure OAuth Scopes

1. Navigate to "OAuth & Permissions" in the sidebar

2. Under "Bot Token Scopes", add the following scopes:

   • search:read - Search workspace content

   • channels:read - View basic channel information

   • groups:read - View basic private channel information

   • im:read - View basic direct message information

   • mpim:read - View basic group direct message information

3. Install App to Workspace

1. Scroll to "OAuth Tokens for Your Workspace"

2. Click "Install to Workspace"

3. Authorize the app

4. Copy the "Bot User OAuth Token" (starts with xoxb-)

4. Set Environment Variable

Export your token as an environment variable:

Or create a .env file (not committed to git):

Installation

Environment Variables

Available MCP Tools

1. search-messages

Search across all accessible Slack messages in your workspace.

Parameters:

• query (required): Search query string

• limit (optional): Number of results to return (1-100, default: 20)

• from_user (optional): Filter by user ID

• in_channel (optional): Filter by channel ID

• after (optional): Filter messages after this date (YYYY-MM-DD)

• before (optional): Filter messages before this date (YYYY-MM-DD)

• exclude_bots (optional): Exclude messages from bots (boolean)

• has_attachments (optional): Only messages with attachments (boolean)

• has_links (optional): Only messages with links (boolean)

Example:

2. search-in-channel

Search messages within a specific Slack channel.

Parameters:

• channel_id (required): Slack channel ID (e.g., C1234567890)

• query (required): Search query string

• limit (optional): Number of results to return (1-100, default: 20)

• from_user (optional): Filter by user ID

• after (optional): Filter messages after this date (YYYY-MM-DD)

• before (optional): Filter messages before this date (YYYY-MM-DD)

• exclude_bots (optional): Exclude messages from bots (boolean)

Example:

MCP Client Configuration

Claude Desktop

Add this to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Other MCP Clients

Connect to the SSE endpoint:

Development

Code Quality

Testing

CI Pipeline

Run the full continuous integration pipeline:

This runs:

1. TypeScript type checking

2. Biome linting

3. Unit tests

4. Mutation tests

Project Structure

Technology Stack

• Runtime: Node.js v22

• Language: TypeScript 5.6+ (ESM modules)

• MCP SDK: @modelcontextprotocol/sdk v1.25.1

• Web Framework: Express v5.2.1

• Validation: Zod v4.2.1

• Testing: Vitest 2.x

• Linter/Formatter: Biome 2.x

• Mutation Testing: Stryker 8.x

License

See LICENSE file for details.

Contributing

1. Follow the TypeScript strictness guidelines in CLAUDE.md

2. Write tests for all new features (80% coverage minimum)

3. Run npm run ci before committing

4. Use named exports only (no default exports)

5. Extract magic numbers to named constants

6. Use bracket notation for process.env access

Troubleshooting

"SLACK_BOT_TOKEN environment variable is required" error

Make sure you've set the SLACK_BOT_TOKEN environment variable:

Search returns no results

1. Verify your bot token has the search:read scope

2. Ensure the bot has been added to channels you want to search

3. Check that your search query matches actual message content

API rate limiting

Slack has rate limits on API calls. If you hit rate limits:

• Reduce the search frequency

• Use more specific queries

• Implement caching (not currently included)

Connection issues

If the MCP client can't connect:

1. Verify the server is running: curl http://localhost:3000/

2. Check the port matches your configuration

3. Review server logs for error messages