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:

export SLACK_BOT_TOKEN="xoxb-your-token-here"

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

SLACK_BOT_TOKEN=xoxb-your-token-here
PORT=3000

Installation

# Install dependencies
npm install

# Run development server with hot reload
npm run dev

# Build for production
npm run build

# Run production server
npm start

Environment Variables

Variable	Required	Default	Description
SLACK_BOT_TOKEN	Yes	-	Slack Bot User OAuth Token (starts with xoxb-)
PORT	No	3000	Port number for the HTTP server

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:

{
  "query": "bug fix",
  "limit": 10,
  "exclude_bots": true,
  "after": "2024-01-01"
}

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:

{
  "channel_id": "C1234567890",
  "query": "deployment",
  "limit": 5
}

MCP Client Configuration

Claude Desktop

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

{
  "mcpServers": {
    "slack": {
      "url": "http://localhost:3000/mcp/slack/sse",
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

Other MCP Clients

Connect to the SSE endpoint:

http://localhost:3000/mcp/slack/sse

Development

Code Quality

# Format and lint code
npm run check

# Type checking only
npm run typecheck

# Linting only
npm run lint

# Format only
npm run format

Testing

# Run tests (watch mode)
npm test

# Run tests with UI
npm run test:ui

# Run tests with coverage (80% threshold)
npm run test:coverage

# Run mutation testing (74% threshold)
npm run test:mutation

CI Pipeline

Run the full continuous integration pipeline:

npm run ci

This runs:

1. TypeScript type checking
2. Biome linting
3. Unit tests
4. Mutation tests

Project Structure

src/
├── mcps/
│   └── slack/
│       ├── __tests__/          # Integration tests
│       ├── services/           # Slack API client
│       │   ├── __tests__/
│       │   └── slack-client.ts
│       ├── tools/              # MCP tool implementations
│       │   ├── __tests__/
│       │   ├── search-messages.ts
│       │   └── search-in-channel.ts
│       └── index.ts            # MCP server setup
├── shared/
│   ├── __tests__/
│   ├── config.ts               # Environment validation
│   └── types.ts                # Shared TypeScript types
└── server.ts                   # HTTP server entry point

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:

export SLACK_BOT_TOKEN="xoxb-your-token-here"

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