README.md•9.69 kB
# Slack MCP Server
**AgenticLedger Platform Integration**
**Version:** 1.0.0
## Overview
The Slack MCP Server enables AI agents to interact with Slack workspaces through standardized Model Context Protocol (MCP) tools. This server provides access to read messages, post updates, manage threads, and discover channels while following AgenticLedger platform security and authentication standards.
**Verified with real Slack data - all core features tested and working!** ✅
## Authentication Pattern
✅ **OAuth (Direct access token)**
This server uses Slack's OAuth tokens directly. The platform handles the OAuth flow and token management - the server simply receives and uses the access token.
## Token Format
```typescript
accessToken: "xoxb-..." // Bot token (recommended)
```
### Required Slack Scopes
Your Slack app needs these OAuth scopes:
**Required for core functionality:**
- `channels:history` - View messages in public channels
- `groups:history` - View messages in private channels
- `im:history` - View messages in direct messages
- `mpim:history` - View messages in group direct messages
- `channels:read` - View basic channel information
- `groups:read` - View basic private channel information
- `users:read` - View user information
- `chat:write` - Post messages to channels and conversations
## Available Tools
### 1. conversations_history
**Description:** Retrieves message history from a Slack channel, DM, or thread with pagination support
**✅ Tested and working with real Slack data!**
**Parameters:**
- `accessToken` (string, required): Slack OAuth token (xoxb-...)
- `channel_id` (string, required): Channel ID (e.g., C1234567890), channel name (#general), or DM (@username)
- `limit` (string|number, optional): Time range (1d, 7d, 1m, 90d) or message count (e.g., 100)
- `cursor` (string, optional): Pagination cursor from previous response
- `include_activity_messages` (boolean, optional): Include join/leave system messages (default: false)
**Example:**
```typescript
{
"accessToken": "xoxb-...",
"channel_id": "#testing",
"limit": 10
}
```
**Response:**
```json
{
"success": true,
"data": {
"messages": [
{
"type": "message",
"user": "U1234567890",
"text": "Hello world!",
"ts": "1234567890.123456"
}
],
"has_more": false,
"cursor": "",
"channel_id": "C1234567890"
}
}
```
---
### 2. conversations_replies
**Description:** Fetches all messages in a specific thread by channel and thread timestamp
**✅ Tested and working with real threads!**
**Parameters:**
- `accessToken` (string, required): Slack OAuth token
- `channel_id` (string, required): Channel ID, name (#general), or DM (@username)
- `thread_ts` (string, required): Message timestamp in format 1234567890.123456
- `limit` (string|number, optional): Time range or message count
- `cursor` (string, optional): Pagination cursor
- `include_activity_messages` (boolean, optional): Include system messages (default: false)
**Example:**
```typescript
{
"accessToken": "xoxb-...",
"channel_id": "#testing",
"thread_ts": "1234567890.123456",
"limit": 50
}
```
**Response:**
```json
{
"success": true,
"data": {
"messages": [
{
"type": "message",
"user": "U1234567890",
"text": "Thread parent message",
"ts": "1234567890.123456",
"thread_ts": "1234567890.123456"
},
{
"type": "message",
"user": "U9876543210",
"text": "Thread reply",
"ts": "1234567890.234567",
"thread_ts": "1234567890.123456"
}
],
"has_more": false,
"channel_id": "C1234567890",
"thread_ts": "1234567890.123456"
}
}
```
---
### 3. conversations_add_message
**Description:** Posts a message to a channel, thread, or DM. Supports markdown and plain text formatting.
**✅ Tested and working - posts to both channels and threads!**
**⚠️ SAFETY NOTE:** This tool is **disabled by default**. To enable, set the `SLACK_MCP_ADD_MESSAGE_TOOL` environment variable to:
- `*` - Enable for all channels
- `C1234567890,C9876543210` - Enable for specific channel IDs (comma-separated)
**Parameters:**
- `accessToken` (string, required): Slack OAuth token with chat:write scope
- `channel_id` (string, required): Target channel ID, name (#general), or DM (@username)
- `thread_ts` (string, optional): Thread timestamp; omit to post to channel directly
- `payload` (string, required): Message content to post
- `content_type` (string, optional): "text/markdown" (default) or "text/plain"
**Example - Post to channel:**
```typescript
{
"accessToken": "xoxb-...",
"channel_id": "#general",
"payload": "Hello from AI agent! 👋",
"content_type": "text/markdown"
}
```
**Example - Post to thread:**
```typescript
{
"accessToken": "xoxb-...",
"channel_id": "#general",
"thread_ts": "1234567890.123456",
"payload": "Reply in thread"
}
```
**Response:**
```json
{
"success": true,
"data": {
"ok": true,
"channel": "C1234567890",
"ts": "1234567890.123456",
"message": {
"text": "Hello from AI agent! 👋",
"type": "message"
}
}
}
```
---
### 4. channels_list
**Description:** Lists workspace channels by type (public, private, DMs, group DMs) with optional popularity sorting
**✅ Tested and working with real workspace data!**
**Parameters:**
- `accessToken` (string, required): Slack OAuth token
- `channel_types` (string, required): Comma-separated values: `mpim`, `im`, `public_channel`, `private_channel`
- `sort` (string, optional): "popularity" to sort by member count
- `limit` (number, optional): Number of results (max: 999, default: 100)
- `cursor` (string, optional): Pagination cursor
**Example:**
```typescript
{
"accessToken": "xoxb-...",
"channel_types": "public_channel,private_channel",
"sort": "popularity",
"limit": 50
}
```
**Response:**
```json
{
"success": true,
"data": {
"channels": [
{
"id": "C1234567890",
"name": "general",
"topic": "Company-wide announcements",
"purpose": "This channel is for team-wide communication",
"member_count": 150,
"is_private": false,
"is_channel": true,
"is_im": false,
"is_mpim": false
}
],
"has_more": false
}
}
```
---
## Installation
```bash
# Install dependencies
npm install
# Build the TypeScript project
npm run build
# Run the server
npm start
```
## Testing
```bash
# Run all tests
npm test
# Run integration tests (requires valid Slack token)
npm run test:integration
```
## Platform Integration Notes
### Environment Variables
- `SLACK_MCP_ADD_MESSAGE_TOOL` - Controls message posting capability:
- Not set (default): Message posting disabled
- `*`: Enable for all channels
- `C123...,C456...`: Enable for specific channel IDs
### Error Handling
The server provides specific error messages for common Slack API errors:
- `channel_not_found` → "Channel not found with the provided ID"
- `invalid_auth` → "Invalid or expired authentication credentials"
- `not_in_channel` → "Bot is not a member of this channel"
- `missing_scope` → "Token is missing required Slack permissions/scopes"
- `rate_limited` → "Rate limited by Slack API - please try again later"
### Rate Limiting
Slack API has rate limits. The server handles rate limit errors gracefully, but consider implementing retry logic in your agent code.
### Channel ID Resolution
The server automatically resolves:
- Channel names: `#general` → `C1234567890`
- DM usernames: `@username` → Opens/finds DM and returns channel ID
- Direct IDs: `C1234567890` → Used as-is
## Technical Specifications
- **Node.js version**: ≥18.0.0
- **Dependencies**:
- `@slack/web-api` - Official Slack Web API client
- `@modelcontextprotocol/sdk` - MCP protocol implementation
- `zod` - Schema validation
- **Language**: TypeScript (ES2022)
- **Transport**: Stdio (MCP standard)
## Known Limitations
1. **Bot Channel Membership:** Bot must be added to channels before reading messages (use `/invite @bot-name` in Slack)
2. **Message Posting Safety:** Disabled by default - requires explicit environment variable configuration
3. **Rate Limits:** Slack enforces rate limits on API calls - implement retry logic for production use
## Real-World Testing Results
This server has been tested with actual Slack workspace data:
**Verified Capabilities:**
- ✅ Read 5+ messages from real channels
- ✅ Read 2-message threads successfully
- ✅ Posted messages to channels (tested live)
- ✅ Posted threaded replies (tested live)
- ✅ Listed 12 real workspace channels
- ✅ Sorted channels by popularity (614 → 143 → 23 members...)
- ✅ All error handling tested with real errors
- ✅ Performance under 300ms for all operations
**What Works:**
- 4/4 tools fully functional with real Slack API ✅
- All core reading and writing capabilities verified ✅
- Channel discovery and management working ✅
See `REAL_TEST_RESULTS.md` for complete testing documentation.
## Platform Configuration Recommendations
### For AgenticLedger Integration:
1. **OAuth Setup**: Configure your Slack OAuth app with the required scopes listed above
2. **Token Storage**: Store tokens securely in the platform's credential management system
3. **Rate Limiting**: Implement platform-level rate limiting and retry logic
4. **Error Monitoring**: Monitor for authentication and permission errors
5. **Audit Logging**: Log all message posting operations for compliance
---
**Built for AgenticLedger Platform**
**Follows MCP Server Build Guide v1.0.0**
**Real-world tested and verified** ✅