Zulip MCP Server

Instructions

Implementation Reference

• src/server.ts:551-578 (handler)

  Main execution logic for the 'get-user-by-email' tool. Fetches user data via Zulip client and returns formatted JSON response.

  async ({ email, client_gravatar, include_custom_profile_fields }) => {
    try {
      const result = await zulipClient.getUserByEmail(email, {
        client_gravatar,
        include_custom_profile_fields
      });
      
      return createSuccessResponse(JSON.stringify({
        user: {
          id: result.user.user_id,
          email: result.user.email,
          full_name: result.user.full_name,
          is_active: result.user.is_active,
          is_bot: result.user.is_bot,
          role: result.user.is_owner ? 'owner' : 
                result.user.is_admin ? 'admin' : 
                result.user.is_moderator ? 'moderator' : 
                result.user.is_guest ? 'guest' : 'member',
          date_joined: result.user.date_joined,
          timezone: result.user.timezone,
          avatar_url: result.user.avatar_url,
          profile_data: result.user.profile_data
        }
      }, null, 2));
    } catch (error) {
      return createErrorResponse(`Error getting user by email: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/types.ts:155-159 (schema)

  Zod input schema defining parameters for the get-user-by-email tool: email (required), optional client_gravatar and include_custom_profile_fields.

  export const GetUserByEmailSchema = z.object({
    email: z.string().email().describe("Email address of the user to look up"),
    client_gravatar: z.boolean().optional().describe("Include Gravatar profile image URL"),
    include_custom_profile_fields: z.boolean().optional().describe("Include organization-specific custom profile fields")
  });

• src/server.ts:547-580 (registration)

  MCP server.tool registration call that defines the tool name, description, schema, and handler function.

  server.tool(
    "get-user-by-email",
    "📧 EXACT LOOKUP: Find a user when you have their exact email address. Use this when you know the specific email and need detailed profile information. Returns single user with complete details.",
    GetUserByEmailSchema.shape,
    async ({ email, client_gravatar, include_custom_profile_fields }) => {
      try {
        const result = await zulipClient.getUserByEmail(email, {
          client_gravatar,
          include_custom_profile_fields
        });
        
        return createSuccessResponse(JSON.stringify({
          user: {
            id: result.user.user_id,
            email: result.user.email,
            full_name: result.user.full_name,
            is_active: result.user.is_active,
            is_bot: result.user.is_bot,
            role: result.user.is_owner ? 'owner' : 
                  result.user.is_admin ? 'admin' : 
                  result.user.is_moderator ? 'moderator' : 
                  result.user.is_guest ? 'guest' : 'member',
            date_joined: result.user.date_joined,
            timezone: result.user.timezone,
            avatar_url: result.user.avatar_url,
            profile_data: result.user.profile_data
          }
        }, null, 2));
      } catch (error) {
        return createErrorResponse(`Error getting user by email: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/zulip/client.ts:386-396 (helper)

  ZulipClient helper method that performs the actual API call to retrieve user by email via GET /users/{email}.

  async getUserByEmail(email: string, params: {
    client_gravatar?: boolean;
    include_custom_profile_fields?: boolean;
  } = {}): Promise<{ user: ZulipUser }> {
    // Filter out undefined values
    const filteredParams = Object.fromEntries(
      Object.entries(params).filter(([, value]) => value !== undefined)
    );
    const response = await this.client.get(`/users/${encodeURIComponent(email)}`, { params: filteredParams });
    return response.data;
  }