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 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:

{
  "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 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:

{
  "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 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:

{
  "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 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:

{
  "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 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 ✅