substack-api-mcp 1.0.2__py3-none-any.whl

substack_api_mcp/substack/tools/create_subscriber_tag.py

@@ -0,0 +1,46 @@
+"""Create subscriber tag."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"name": {"type": "string", "description": "Tag name, e.g. Early readers."}},
+    "required": ["name"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"tag_id": "9357", "name": "Early readers"}
+
+
+@tool(
+    name="create_subscriber_tag",
+    title="Create subscriber tag",
+    access="write",
+    confirm=False,
+    description="New private tag for grouping subscribers.",
+    details=(
+        "Creates a subscriber tag on your publication. Tags are private: subscribers never see them. Put "
+        "subscribers under it with tag_subscribers."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /subscriber-tags",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def create_subscriber_tag(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    name = str(args["name"]).strip()
+    if not name or len(name) > 100:
+        raise ToolError("name must be 1 to 100 characters.", ErrorCode.INVALID_INPUT)
+    pub = await publication(ctx)
+    answer = await call(ctx, "POST", f"{pub['base']}/api/v1/subscriber-tags", body={"name": name})
+    tag = answer.get("tag") or answer
+    return {"tag_id": str(tag["id"]), "name": tag.get("name") or name}

substack_api_mcp/substack/tools/delete_comment.py

@@ -0,0 +1,45 @@
+"""Delete comment or Note."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call, comment_id
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "comment_id": {"type": "string", "description": "ID of your comment, Note or Note reply."},
+    },
+    "required": ["comment_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"comment_id": "364150154", "deleted": True}
+
+
+@tool(
+    name="delete_comment",
+    title="Delete comment or Note",
+    access="write",
+    confirm=True,
+    description="Delete one of your own comments, Notes or Note replies.",
+    details=(
+        "Deletes something you wrote: a comment under a post, a Note or a reply to a Note. Replies other "
+        "people wrote under it stay, under a deleted placeholder. Someone else's comment returns an error; "
+        "on your own posts remove it with remove_comment. By default you confirm each call; you can switch "
+        "that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="DELETE /comments/{comment_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def delete_comment(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    cid = comment_id(args["comment_id"])
+    await call(ctx, "DELETE", f"{WEB}/api/v1/comment/{cid}")
+    return {"comment_id": str(cid), "deleted": True}

substack_api_mcp/substack/tools/delete_post.py

@@ -0,0 +1,47 @@
+"""Delete post."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, draft, post_id, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "post_id": {"type": "string", "description": "Post ID from list_posts."},
+    },
+    "required": ["post_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"post_id": "148213977", "title": "Notes on slow mornings", "deleted": True}
+
+
+@tool(
+    name="delete_post",
+    title="Delete post",
+    access="write",
+    confirm=True,
+    description="Delete a draft, scheduled or published post, with its comments.",
+    details=(
+        "Deletes one post of your publication for good: a draft, a scheduled post (its send is cancelled) or "
+        "a published post, which leaves the web, the archive and the app with its comments and stats. Emails "
+        "already sent stay in inboxes. Substack has no undo; unpublish_post keeps the post as a draft instead. "
+        "By default you confirm each call; you can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="DELETE /posts/{post_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def delete_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    post = await draft(ctx, pub, pid)
+    await call(ctx, "DELETE", f"{pub['base']}/api/v1/drafts/{pid}")
+    return {"post_id": str(pid), "title": post.get("title") or post.get("draft_title") or "", "deleted": True}

substack_api_mcp/substack/tools/duplicate_post.py

@@ -0,0 +1,55 @@
+"""Duplicate post."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, post_id, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "post_id": {"type": "string", "description": "Post ID from list_posts."},
+    },
+    "required": ["post_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "post_id": "148214502",
+    "source_post_id": "148213977",
+    "title": "[COPY] Notes on slow mornings",
+    "edit_url": "https://yourname.substack.com/publish/post/148214502",
+}
+
+
+@tool(
+    name="duplicate_post",
+    title="Duplicate post",
+    access="write",
+    confirm=False,
+    description="Copy any post into a new draft.",
+    details=(
+        "Makes a new draft with the title, subtitle, body and settings of a draft or published post, as "
+        "Duplicate in the post list does. Substack puts [COPY] in front of the title; change it with "
+        "update_draft. Nothing is published or sent."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /posts/{post_id}/duplicate",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def duplicate_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    copy = await call(ctx, "POST", f"{pub['base']}/api/v1/posts/{pid}/duplicate")
+    return {
+        "post_id": str(copy["id"]),
+        "source_post_id": str(pid),
+        "title": copy.get("draft_title") or "",
+        "edit_url": f"{pub['base']}/publish/post/{copy['id']}",
+    }

substack_api_mcp/substack/tools/export_subscribers.py

@@ -0,0 +1,42 @@
+"""Export subscribers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import publication
+from substack_api_mcp.substack.subscribers import export
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {"type": "object", "properties": {}, "required": [], "additionalProperties": False}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "download_url": "https://substack-post-media.s3.us-east-1.amazonaws.com/publication_export/7f3c2a.csv?X-Amz-Expires=86400&X-Amz-Signature=...",
+    "rows": 4380,
+    "expires_at": "2026-10-12T10:00:00+00:00",
+}
+
+
+@tool(
+    name="export_subscribers",
+    title="Export subscribers",
+    access="read",
+    confirm=False,
+    description="The full subscriber list as a CSV download link, with the row count.",
+    details=(
+        "Builds the same CSV as Export in the subscriber dashboard: email, name, subscription type, activity "
+        "rating and start date. Substack builds the file in the background; the call waits up to about a "
+        "minute and otherwise asks you to try again later. The link needs no sign-in and works until "
+        "expires_at, 24 hours when we recorded it. For filtered pages use list_subscribers."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /subscribers/export",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def export_subscribers(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    return await export(ctx, pub)

substack_api_mcp/substack/tools/follow_user.py

@@ -0,0 +1,46 @@
+"""Follow user."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call, user_ref
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "user": {"type": "string", "description": "Handle (e.g. @mayachen) or user ID."},
+        "unfollow": {"type": "boolean", "description": "Unfollow instead. Default: false."},
+    },
+    "required": ["user"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"user_id": "41856304", "handle": "mayachen", "following": True}
+
+
+@tool(
+    name="follow_user",
+    title="Follow user",
+    access="write",
+    confirm=False,
+    description="Follow or unfollow a Substack user, so their Notes reach your feed.",
+    details=(
+        "Follows a person on Substack, as Follow on their profile does, or unfollows them. Following is not "
+        "subscribing: you get their Notes and activity in the app, not their newsletter by email. They see "
+        "the follow."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PUT /users/{user}/follow",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def follow_user(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    user = await user_ref(ctx, args["user"])
+    unfollow = bool(args.get("unfollow"))
+    await call(ctx, "DELETE" if unfollow else "POST", f"{WEB}/api/v1/feed/{user['id']}/follow")
+    return {"user_id": str(user["id"]), "handle": user["handle"], "following": not unfollow}

substack_api_mcp/substack/tools/get_audience_insights.py

@@ -0,0 +1,93 @@
+"""Get audience insights."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "region": {
+            "type": "string",
+            "enum": ["world", "usa"],
+            "description": "world (by country) or usa (by state). Default: world.",
+        },
+        "paid_only": {"type": "boolean", "description": "Count paid subscribers only. Default: false."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "region": "world",
+    "metric": "all subscribers",
+    "countries_total": 41,
+    "us_states_total": 38,
+    "locations": [{"location": "us", "subscribers": 2310}, {"location": "gb", "subscribers": 402}],
+    "overlap": [
+        {
+            "publication_id": "5262902",
+            "name": "Brain Health Decoded",
+            "url": "https://example.substack.com",
+            "overlap_percent": 6.4,
+        }
+    ],
+}
+
+
+@tool(
+    name="get_audience_insights",
+    title="Get audience insights",
+    access="read",
+    confirm=False,
+    description="Where your subscribers live, and which publications share your readers.",
+    details=(
+        "Returns Analytics > Statistics > Audience: subscriber counts per country (region world, ISO codes "
+        "such as us, gb) or per US state (region usa, codes such as ny, ca), all subscribers or paid only, "
+        "the number of countries and states with any subscriber, and the publications whose readers "
+        "overlap most with yours. Substack computes these in the background; a new publication has empty "
+        "lists for a while."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /audience",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_audience_insights(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    region = args.get("region") or "world"
+    metric = "paid subscribers" if args.get("paid_only") else "free signups"
+    pub = await publication(ctx)
+    stats = f"{pub['base']}/api/v1/publication/stats/audience_insights"
+    params = {"metric": metric, "granularity": "usa" if region == "usa" else "global"}
+    rows = await call(ctx, "GET", f"{stats}/location", params=params) or []
+    totals = await call(ctx, "GET", f"{stats}/location/total") or {}
+    overlap = await call(ctx, "GET", f"{stats}/overlap", params={"limit": 10}) or []
+    locations = sorted(
+        (
+            {"location": str(row.get("location") or "").lower(), "subscribers": int(row.get("value") or 0)}
+            for row in rows
+        ),
+        key=lambda row: -row["subscribers"],
+    )
+    return {
+        "region": region,
+        "metric": "paid subscribers" if args.get("paid_only") else "all subscribers",
+        "countries_total": int((totals.get("global") or {}).get("locations") or 0),
+        "us_states_total": int((totals.get("usa") or {}).get("locations") or 0),
+        "locations": locations,
+        "overlap": [
+            {
+                "publication_id": str((row.get("pub") or {}).get("id") or ""),
+                "name": (row.get("pub") or {}).get("name") or "",
+                "url": (row.get("pub") or {}).get("base_url"),
+                "overlap_percent": row.get("percentOverlap"),
+            }
+            for row in overlap
+        ],
+    }

substack_api_mcp/substack/tools/get_conversation.py

@@ -0,0 +1,71 @@
+"""Get conversation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call, person
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "conversation_id": {"type": "string", "description": "Conversation ID from list_conversations."},
+    },
+    "required": ["conversation_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "conversation_id": "112992a4-5356-4bd2-8a16-f940cabbb4df",
+    "members": [{"user_id": "41856304", "name": "Maya Chen", "handle": "mayachen"}],
+    "messages": [
+        {
+            "from": {"user_id": "561078443", "name": "Sam Ortiz", "handle": "samortiz"},
+            "body": "Hi, saw your Substack launch. Good luck with it!",
+            "sent_at": "2026-10-18T15:55:22.545Z",
+        }
+    ],
+}
+
+
+@tool(
+    name="get_conversation",
+    title="Get conversation",
+    access="read",
+    confirm=False,
+    description="The latest messages of one direct-message conversation, oldest first.",
+    details=(
+        "Returns who is in the conversation and its latest messages as the chat window first shows them, "
+        "oldest first, with sender, text and time. Opening a conversation this way marks nothing read."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /conversations/{conversation_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_conversation(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    thread_id = str(args["conversation_id"]).strip().removeprefix("direct-message-")
+    if not thread_id or "/" in thread_id:
+        raise ToolError("conversation_id must be the ID from list_conversations.", ErrorCode.INVALID_INPUT)
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/messages/dm/{thread_id}")
+    thread = answer.get("thread") or {}
+    messages = [
+        {
+            "from": person(row.get("user") or {"id": (row.get("comment") or {}).get("user_id")}),
+            "body": (row.get("comment") or {}).get("body") or "",
+            "sent_at": (row.get("comment") or {}).get("created_at"),
+        }
+        for row in answer.get("replies") or []
+        if row.get("comment")
+    ]
+    messages.sort(key=lambda message: message["sent_at"] or "")
+    return {
+        "conversation_id": thread.get("id") or thread_id,
+        "members": [person(member.get("user")) for member in thread.get("members") or []],
+        "messages": messages,
+    }

substack_api_mcp/substack/tools/get_daily_stats.py

@@ -0,0 +1,77 @@
+"""Get daily stats."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"period": {"type": "string", "enum": ["7d", "30d", "90d", "365d"], "description": "Default: 30d."}},
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "period": "7d",
+    "days": [{"date": "2026-10-18", "subscribers": 4380, "paid_subscribers": 412, "followers": 5120, "views": 1893}],
+}
+
+
+@tool(
+    name="get_daily_stats",
+    title="Get daily stats",
+    access="read",
+    confirm=False,
+    description="Day by day: total and paid subscribers, followers and views.",
+    details=(
+        "Returns one row per day of the period, as the charts on the dashboard home and in Audience: total "
+        "subscribers, paid subscribers and followers at the end of the day, and the day's views across your "
+        "site and the app. Days Substack has no number for are null; a young publication starts on the day "
+        "it was made."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /stats/daily",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_daily_stats(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    period = args.get("period") or "30d"
+    pub = await publication(ctx)
+    since = (datetime.now(UTC) - timedelta(days=int(period[:-1]))).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+    stats = f"{pub['base']}/api/v1/publication/stats"
+    columns = {
+        "subscribers": await _series(ctx, f"{stats}/emails/timeseries", since),
+        "paid_subscribers": await _series(ctx, f"{stats}/subscribers/timeseries", since, "Paid"),
+        "followers": await _series(ctx, f"{stats}/followers/timeseries", since),
+        "views": await _series(ctx, f"{stats}/publication_traffic/timeseries", since, resolution="day"),
+    }
+    dates = sorted({date for series in columns.values() for date in series})
+    return {
+        "period": period,
+        "days": [{"date": date, **{name: series.get(date) for name, series in columns.items()}} for date in dates],
+    }
+
+
+async def _series(
+    ctx: ToolContext, url: str, since: str, column: str | None = None, resolution: str | None = None
+) -> dict[str, int | None]:
+    """A dashboard chart as {date: value}. Rows are [date, value]; with a header row, `column` picks the value."""
+    params = {"from": since, **({"resolution": resolution} if resolution else {})}
+    rows = await call(ctx, "GET", url, params=params) or []
+    index = 1
+    if rows and isinstance(rows[0], list) and rows[0] and rows[0][0] == "Date":
+        index = rows[0].index(column) if column in rows[0] else 1
+        rows = rows[1:]
+    series: dict[str, int | None] = {}
+    for row in rows:
+        if isinstance(row, list) and len(row) > index:
+            value = row[index]
+            series[str(row[0]).replace("/", "-")] = int(value) if isinstance(value, int | float) else None
+    return series

substack_api_mcp/substack/tools/get_feed.py

@@ -0,0 +1,83 @@
+"""Get feed."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call
+from substack_api_mcp.substack.feed import note_item, post_item
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "tab": {
+            "type": "string",
+            "enum": ["for_you", "following"],
+            "description": "for_you (Substack's picks) or following (whom you follow). Default: for_you.",
+        },
+        "cursor": {"type": "string", "description": "next_cursor from the previous page."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "tab": "following",
+    "posts": [
+        {
+            "post_id": "197396217",
+            "title": "A Guide to Your Morning Routine",
+            "publication": "Brain Health Decoded",
+            "publication_id": "5262902",
+            "published_at": "2026-05-12T19:25:47.700Z",
+            "likes": 410,
+            "url": "https://example.substack.com/p/a-guide-to-your-morning-routine",
+        }
+    ],
+    "notes": [
+        {
+            "note_id": "322981144",
+            "author": {"user_id": "18270011", "name": "Laura Mills", "handle": "lauramills"},
+            "body": "Morning light beats any supplement.",
+            "published_at": "2026-09-02T07:11:00.000Z",
+            "likes": 88,
+        }
+    ],
+    "next_cursor": "eyJzZXNzaW9uX2lkIjoiZWQzOCJ9",
+}
+
+
+@tool(
+    name="get_feed",
+    title="Get feed",
+    access="read",
+    confirm=False,
+    description="Your Substack home feed: posts and Notes, For you or Following.",
+    details=(
+        "Returns one page of the home feed of the Substack app, split into posts and Notes in feed order. "
+        "for_you is Substack's own mix; following holds only people and publications you follow or "
+        "subscribe to. Suggestions of people to follow are left out. Reading marks nothing seen. Page with "
+        "next_cursor; the feed is personal and changes between calls."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /feed",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_feed(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    tab = args.get("tab") or "for_you"
+    params = {"tab": "subscribed" if tab == "following" else "for-you", "type": "base"}
+    if args.get("cursor"):
+        params["cursor"] = args["cursor"]
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/reader/feed", params=params)
+    items = answer.get("items") or []
+    return {
+        "tab": tab,
+        "posts": [post_item(item) for item in items if item.get("type") == "post" and item.get("post")],
+        "notes": [note_item(item) for item in items if item.get("type") == "comment" and item.get("comment")],
+        "next_cursor": answer.get("nextCursor"),
+    }