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
- Go to https://api.slack.com/apps
- Click "Create New App" and choose "From scratch"
- Give your app a name (e.g., "MCP Search Bot") and select your workspace
- Click "Create App"
2. Configure OAuth Scopes
- Navigate to "OAuth & Permissions" in the sidebar
- Under "Bot Token Scopes", add the following scopes:
search:read- Search workspace contentchannels:read- View basic channel informationgroups:read- View basic private channel informationim:read- View basic direct message informationmpim:read- View basic group direct message information
3. Install App to Workspace
- Scroll to "OAuth Tokens for Your Workspace"
- Click "Install to Workspace"
- Authorize the app
- 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 stringlimit(optional): Number of results to return (1-100, default: 20)from_user(optional): Filter by user IDin_channel(optional): Filter by channel IDafter(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 stringlimit(optional): Number of results to return (1-100, default: 20)from_user(optional): Filter by user IDafter(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:
- TypeScript type checking
- Biome linting
- Unit tests
- 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
- Follow the TypeScript strictness guidelines in
CLAUDE.md - Write tests for all new features (80% coverage minimum)
- Run
npm run cibefore committing - Use named exports only (no default exports)
- Extract magic numbers to named constants
- Use bracket notation for
process.envaccess
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
- Verify your bot token has the
search:readscope - Ensure the bot has been added to channels you want to search
- 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:
- Verify the server is running:
curl http://localhost:3000/ - Check the port matches your configuration
- Review server logs for error messages