get_subscriber_count

Instructions

Implementation Reference

• src/api/client.ts:70-93 (handler)

  The getSubscriberCount() method in SubstackClient that makes the actual API call to fetch subscriber count from Substack's publication_launch_checklist endpoint.

  async getSubscriberCount(): Promise<{ count: number; note: string }> {
    // Try multiple endpoints — Substack's API is inconsistent
    try {
      const data = await this.request<Record<string, unknown>>(
        `${this.publicationUrl}/api/v1/publication_launch_checklist`,
      );
      if (typeof data.subscriber_count === "number") {
        return { count: data.subscriber_count, note: "exact" };
      }
      if (typeof data.subscriberCount === "number") {
        return { count: data.subscriberCount, note: "exact" };
      }
      // The subscribers field is a paginated sample, not the full list
      if (Array.isArray(data.subscribers)) {
        return {
          count: data.subscribers.length,
          note: "sample only — this is a paginated subset, not the total. Check your Substack dashboard for the exact count.",
        };
      }
    } catch {
      // Fall through
    }
    return { count: -1, note: "Could not retrieve subscriber count. Check your Substack dashboard." };
  }

• src/server.ts:14-26 (registration)

  The MCP tool registration for 'get_subscriber_count' using server.tool(), with empty schema and handler that calls client.getSubscriberCount().

  server.tool(
    "get_subscriber_count",
    "Get the current subscriber count for your Substack publication",
    {},
    async () => {
      const result = await client.getSubscriberCount();
      return {
        content: [
          { type: "text", text: JSON.stringify(result, null, 2) },
        ],
      };
    },
  );

• src/api/types.ts:72-75 (schema)

  The PublicationLaunchChecklist interface type that defines the expected shape of the API response including subscriber_count.

  export interface PublicationLaunchChecklist {
    subscriber_count: number;
    [key: string]: unknown;
  }

• src/api/client.ts:70-93 (handler)

  The getSubscriberCount() method in SubstackClient that makes the actual API call to fetch subscriber count from Substack's publication_launch_checklist endpoint.

  async getSubscriberCount(): Promise<{ count: number; note: string }> {
    // Try multiple endpoints — Substack's API is inconsistent
    try {
      const data = await this.request<Record<string, unknown>>(
        `${this.publicationUrl}/api/v1/publication_launch_checklist`,
      );
      if (typeof data.subscriber_count === "number") {
        return { count: data.subscriber_count, note: "exact" };
      }
      if (typeof data.subscriberCount === "number") {
        return { count: data.subscriberCount, note: "exact" };
      }
      // The subscribers field is a paginated sample, not the full list
      if (Array.isArray(data.subscribers)) {
        return {
          count: data.subscribers.length,
          note: "sample only — this is a paginated subset, not the total. Check your Substack dashboard for the exact count.",
        };
      }
    } catch {
      // Fall through
    }
    return { count: -1, note: "Could not retrieve subscriber count. Check your Substack dashboard." };
  }