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
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 channelsgroups:history- View messages in private channelsim:history- View messages in direct messagesmpim:history- View messages in group direct messageschannels:read- View basic channel informationgroups:read- View basic private channel informationusers:read- View user informationchat: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 responseinclude_activity_messages(boolean, optional): Include join/leave system messages (default: false)
Example:
{
"accessToken": "xoxb-...",
"channel_id": "#testing",
"limit": 10
}
Response:
{
"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 tokenchannel_id(string, required): Channel ID, name (#general), or DM (@username)thread_ts(string, required): Message timestamp in format 1234567890.123456limit(string|number, optional): Time range or message countcursor(string, optional): Pagination cursorinclude_activity_messages(boolean, optional): Include system messages (default: false)
Example:
{
"accessToken": "xoxb-...",
"channel_id": "#testing",
"thread_ts": "1234567890.123456",
"limit": 50
}
Response:
{
"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 channelsC1234567890,C9876543210- Enable for specific channel IDs (comma-separated)
Parameters:
accessToken(string, required): Slack OAuth token with chat:write scopechannel_id(string, required): Target channel ID, name (#general), or DM (@username)thread_ts(string, optional): Thread timestamp; omit to post to channel directlypayload(string, required): Message content to postcontent_type(string, optional): "text/markdown" (default) or "text/plain"
Example - Post to channel:
{
"accessToken": "xoxb-...",
"channel_id": "#general",
"payload": "Hello from AI agent! 👋",
"content_type": "text/markdown"
}
Example - Post to thread:
{
"accessToken": "xoxb-...",
"channel_id": "#general",
"thread_ts": "1234567890.123456",
"payload": "Reply in thread"
}
Response:
{
"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 tokenchannel_types(string, required): Comma-separated values:mpim,im,public_channel,private_channelsort(string, optional): "popularity" to sort by member countlimit(number, optional): Number of results (max: 999, default: 100)cursor(string, optional): Pagination cursor
Example:
{
"accessToken": "xoxb-...",
"channel_types": "public_channel,private_channel",
"sort": "popularity",
"limit": 50
}
Response:
{
"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
# Install dependencies
npm install
# Build the TypeScript project
npm run build
# Run the server
npm start
Testing
# 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 channelsC123...,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 implementationzod- Schema validation
- Language: TypeScript (ES2022)
- Transport: Stdio (MCP standard)
Known Limitations
- Bot Channel Membership: Bot must be added to channels before reading messages (use
/invite @bot-namein Slack) - Message Posting Safety: Disabled by default - requires explicit environment variable configuration
- 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:
- OAuth Setup: Configure your Slack OAuth app with the required scopes listed above
- Token Storage: Store tokens securely in the platform's credential management system
- Rate Limiting: Implement platform-level rate limiting and retry logic
- Error Monitoring: Monitor for authentication and permission errors
- 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 ✅