Zulip MCP Server

Instructions

Implementation Reference

• src/server.ts:801-819 (handler)

  The main tool handler function that destructures input parameters, calls the Zulip client to fetch stream data, formats the response with selected fields, and handles errors.

  async ({ stream_id, include_subscribers }) => {
    try {
      const result = await zulipClient.getStream(stream_id, include_subscribers);
      return createSuccessResponse(JSON.stringify({
        stream: {
          id: result.stream.stream_id,
          name: result.stream.name,
          description: result.stream.description,
          invite_only: result.stream.invite_only,
          is_web_public: result.stream.is_web_public,
          is_archived: result.stream.is_archived,
          is_announcement_only: result.stream.is_announcement_only,
          date_created: new Date(result.stream.date_created * 1000).toISOString()
        }
      }, null, 2));
    } catch (error) {
      return createErrorResponse(`Error getting stream by ID: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/types.ts:246-249 (schema)

  Zod schema defining the input parameters: required stream_id (number) and optional include_subscribers (boolean).

  export const GetStreamByIdSchema = z.object({
    stream_id: z.number().describe("Unique stream ID to get details for"),
    include_subscribers: z.boolean().optional().describe("Include subscriber list")
  });

• src/server.ts:797-820 (registration)

  Registers the tool with the MCP server using server.tool(), providing the tool name, description, input schema, and inline handler function.

  server.tool(
    "get-stream-by-id",
    "📊 STREAM DETAILS: Get comprehensive information about a stream (channel) when you have its numeric ID. Returns stream settings, description, subscriber count, etc.",
    GetStreamByIdSchema.shape,
    async ({ stream_id, include_subscribers }) => {
      try {
        const result = await zulipClient.getStream(stream_id, include_subscribers);
        return createSuccessResponse(JSON.stringify({
          stream: {
            id: result.stream.stream_id,
            name: result.stream.name,
            description: result.stream.description,
            invite_only: result.stream.invite_only,
            is_web_public: result.stream.is_web_public,
            is_archived: result.stream.is_archived,
            is_announcement_only: result.stream.is_announcement_only,
            date_created: new Date(result.stream.date_created * 1000).toISOString()
          }
        }, null, 2));
      } catch (error) {
        return createErrorResponse(`Error getting stream by ID: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/zulip/client.ts:362-366 (helper)

  ZulipClient helper method that makes the actual HTTP GET request to Zulip API endpoint /streams/{streamId} to fetch stream details, optionally including subscribers.

  async getStream(streamId: number, includeSubscribers?: boolean): Promise<{ stream: ZulipStream }> {
    const params = includeSubscribers ? { include_subscribers: true } : {};
    const response = await this.client.get(`/streams/${streamId}`, { params });
    return response.data;
  }