substack-mcp

Instructions

Implementation Reference

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

  The getSubscriberCount() method in SubstackClient fetches subscriber count from Substack's publication_launch_checklist API endpoint. It handles multiple possible response formats (subscriber_count, subscriberCount, subscribers array) and returns both the count and a note indicating the data quality/source.

  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)

  Registration of the get_subscriber_count tool with the MCP server. The tool has an empty schema (no parameters), a description, and an async handler that calls client.getSubscriberCount() and returns the result as formatted JSON.

  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) },
        ],
      };
    },
  );