Slack MCP Server

Instructions

Implementation Reference

• src/tools.ts:138-179 (handler)

  The main handler function `conversationsHistory` that executes the tool logic: validates input with Zod schema, resolves channel ID, parses limit parameters, fetches history from Slack API using WebClient, filters messages, handles pagination and errors.

  export async function conversationsHistory(args: any): Promise<ToolResponse> {
    try {
      const validated = ConversationsHistorySchema.parse(args);
      const client = new WebClient(validated.accessToken);
  
      console.log('Fetching conversation history for channel:', validated.channel_id);
  
      // Resolve channel name/username to ID if needed
      const channelId = await resolveChannelId(client, validated.channel_id);
  
      // Parse limit parameter
      const limitParams = parseLimit(validated.limit);
  
      // Fetch conversation history
      const result = await client.conversations.history({
        channel: channelId,
        cursor: validated.cursor,
        ...limitParams
      });
  
      // Filter out activity messages if not requested
      let messages = result.messages || [];
      if (!validated.include_activity_messages) {
        messages = messages.filter((msg: any) => !msg.subtype || !['channel_join', 'channel_leave'].includes(msg.subtype));
      }
  
      return {
        success: true,
        data: {
          messages,
          has_more: result.has_more,
          cursor: result.response_metadata?.next_cursor,
          channel_id: channelId
        }
      };
    } catch (error: any) {
      if (error.name === 'ZodError') {
        return { success: false, error: `Validation error: ${error.errors.map((e: any) => e.message).join(', ')}` };
      }
      return handleSlackError(error);
    }
  }

• src/schemas.ts:7-13 (schema)

  Zod schema `ConversationsHistorySchema` defining the input parameters and validation for the conversations_history tool.

  export const ConversationsHistorySchema = z.object({
    accessToken: z.string().describe("Slack OAuth token (xoxp-... or xoxb-...)"),
    channel_id: z.string().describe("Channel ID (e.g., C1234567890), channel name (#general), or DM (@username)"),
    limit: z.union([z.string(), z.number()]).optional().describe("Time range (1d, 7d, 1m, 90d) or message count (e.g., 100)"),
    cursor: z.string().optional().describe("Pagination cursor from previous response"),
    include_activity_messages: z.boolean().optional().describe("Include join/leave system messages (default: false)")
  });

• src/index.ts:95-99 (registration)

  Tool registration in the MCP server's `listTools` response, specifying name, description, and converted input schema.

  {
    name: 'conversations_history',
    description: 'Retrieves message history from a Slack channel, DM, or thread. Supports pagination and filtering.',
    inputSchema: zodToMCPSchema(ConversationsHistorySchema)
  },

• src/index.ts:129-131 (registration)

  Dispatch registration in the MCP server's `callTool` request handler switch statement that invokes the handler function.

  case 'conversations_history':
    result = await conversationsHistory(args);
    break;

• src/tools.ts:64-95 (helper)

  Helper function `resolveChannelId` used by the handler to convert channel names (#channel) or usernames (@user) to actual Slack channel IDs.

  async function resolveChannelId(client: WebClient, channelInput: string): Promise<string> {
    // If already an ID (starts with C, D, or G), return as-is
    if (/^[CDG][A-Z0-9]+$/.test(channelInput)) {
      return channelInput;
    }
  
    // Handle #channel format
    if (channelInput.startsWith('#')) {
      const channelName = channelInput.slice(1);
      const result = await client.conversations.list({ types: 'public_channel,private_channel' });
      const channel = result.channels?.find((ch: any) => ch.name === channelName);
      if (channel) {
        return channel.id!;
      }
      throw new Error(`Channel not found: ${channelInput}`);
    }
  
    // Handle @username format for DMs
    if (channelInput.startsWith('@')) {
      const username = channelInput.slice(1);
      const usersResult = await client.users.list({});
      const user = usersResult.members?.find((u: any) => u.name === username);
      if (user) {
        // Open or get existing DM
        const dmResult = await client.conversations.open({ users: user.id! });
        return dmResult.channel!.id!;
      }
      throw new Error(`User not found: ${channelInput}`);
    }
  
    return channelInput; // Return as-is if no special format
  }