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

substack_api_mcp/substack/tools/get_post.py

@@ -0,0 +1,75 @@
+"""Get 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 (
+    body_doc,
+    draft,
+    post_id,
+    post_status,
+    post_url,
+    publication,
+    scheduled_at,
+)
+from substack_api_mcp.substack.markdown import to_markdown
+
+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": "The quiet launch",
+    "subtitle": "What waiting taught me",
+    "body_markdown": "Last month I shipped without telling anyone...",
+    "audience": "everyone",
+    "status": "published",
+    "published_at": "2026-10-06T12:00:00Z",
+    "url": "https://yourname.substack.com/p/the-quiet-launch",
+}
+
+
+@tool(
+    name="get_post",
+    title="Get post",
+    access="read",
+    confirm=False,
+    description="Full post: title, subtitle, body as Markdown, audience, URL and dates.",
+    details=(
+        "Returns one post of your publication, draft, scheduled or published, with its full body as Markdown, "
+        "including the paywalled part. Images come back as URLs. Buttons, embeds and footnotes come back as "
+        "plain text, so writing the body back with update_draft drops them. A scheduled post also has "
+        "publish_at."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /posts/{post_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    post = await draft(ctx, pub, post_id(args["post_id"]))
+    published = bool(post.get("is_published"))
+    status = post_status(post)
+    answer = {
+        "post_id": str(post["id"]),
+        "title": (post.get("title") if published else None) or post.get("draft_title") or "",
+        "subtitle": (post.get("subtitle") if published else None) or post.get("draft_subtitle") or "",
+        "body_markdown": to_markdown(body_doc(post)),
+        "audience": post.get("audience"),
+        "status": status,
+        "published_at": post.get("post_date") if published else None,
+        "url": post_url(pub, post),
+    }
+    if status == "scheduled":
+        answer["publish_at"] = scheduled_at(post)
+    return answer

substack_api_mcp/substack/tools/get_post_engagement.py

@@ -0,0 +1,68 @@
+"""Get post engagement."""
+
+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, person, 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",
+    "likes": 142,
+    "liked_by": [{"user_id": "41856304", "name": "Maya Chen", "handle": "mayachen"}],
+    "comments": 18,
+    "commenters": 11,
+    "commented_by": [{"user_id": "81309935", "name": "Sam Ortiz", "handle": "samortiz"}],
+    "free_signups": 9,
+    "paid_subscriptions": 1,
+    "unsubscribes": 2,
+}
+
+
+@tool(
+    name="get_post_engagement",
+    title="Get post engagement",
+    access="read",
+    confirm=False,
+    description="Who liked and commented on a post, and the subscribers it won and lost.",
+    details=(
+        "Returns the Engagement and Growth parts of a post's stats: like and comment counts with the people "
+        "behind them (name and handle, never email), and the free signups, paid subscriptions and "
+        "unsubscribes Substack credits to the post. Counts keep changing for days after a send."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /posts/{post_id}/engagement",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_post_engagement(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    base = f"{pub['base']}/api/v1/post_management/detail/{pid}"
+    engagement = await call(ctx, "GET", f"{base}/engagement")
+    growth = await call(ctx, "GET", f"{base}/growth")
+    likes = engagement.get("likes") or {}
+    commenters = engagement.get("commenters") or {}
+    totals = (growth.get("subscribes") or {}).get("totals") or {}
+    return {
+        "post_id": str(pid),
+        "likes": int(likes.get("count") or 0),
+        "liked_by": [person(user) for user in likes.get("users") or []],
+        "comments": int((engagement.get("commentSummary") or {}).get("total") or 0),
+        "commenters": int(commenters.get("count") or 0),
+        "commented_by": [person(user) for user in commenters.get("users") or []],
+        "free_signups": int((growth.get("signups") or {}).get("total") or 0),
+        "paid_subscriptions": int(totals.get("subscribes") or 0),
+        "unsubscribes": int((growth.get("unsubscribes") or {}).get("total") or 0),
+    }

substack_api_mcp/substack/tools/get_post_stats.py

@@ -0,0 +1,73 @@
+"""Get post stats."""
+
+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, 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",
+    "recipients": 4120,
+    "opens": 2011,
+    "open_rate": 0.488,
+    "views": 3560,
+    "likes": 142,
+    "restacks": 18,
+    "subscribers_gained": 37,
+}
+
+
+@tool(
+    name="get_post_stats",
+    title="Get post stats",
+    access="read",
+    confirm=False,
+    description="Recipients, opens, open rate, views, likes, restacks and subscribers gained.",
+    details=(
+        "Returns the engagement numbers of one published post, as on its stats page in the dashboard. Email "
+        "numbers cover the send; views include the web; likes are reactions. A draft or scheduled post "
+        "returns an error. Numbers keep growing for days after a send, so check again later."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /posts/{post_id}/stats",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_post_stats(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    detail = await call(
+        ctx, "GET", f"{pub['base']}/api/v1/post_management/detail/{pid}", params={"offset": 0, "limit": 1}
+    )
+    rows = detail.get("posts") or []
+    if not rows or not rows[0].get("is_published"):
+        raise ToolError("This post is not published, so it has no stats yet.", ErrorCode.INVALID_INPUT)
+    post = rows[0]
+    stats = post.get("stats") or {}
+    # Restacks are counted only on the public post.
+    public = await call(ctx, "GET", f"{pub['base']}/api/v1/posts/{post['slug']}")
+    sent = int(stats.get("sent") or 0)
+    opened = int(stats.get("opened") or 0)
+    return {
+        "post_id": str(pid),
+        "recipients": sent,
+        "opens": opened,
+        "open_rate": round(opened / sent, 3) if sent else 0.0,
+        "views": int(stats.get("views") or 0),
+        "likes": int(post.get("reaction_count") or 0),
+        "restacks": int(public.get("restacks") or 0),
+        "subscribers_gained": int(stats.get("signups") or 0),
+    }

substack_api_mcp/substack/tools/get_post_traffic.py

@@ -0,0 +1,72 @@
+"""Get post traffic."""
+
+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": "148213977",
+    "sources": [{"source": "substack app", "views": 812, "share": 0.41, "free_signups": 12, "paid_subscriptions": 2}],
+    "categories": [{"category": "Substack", "share": 0.58}],
+    "devices": [{"device": "mobile", "share": 0.66}],
+}
+
+
+@tool(
+    name="get_post_traffic",
+    title="Get post traffic",
+    access="read",
+    confirm=False,
+    description="Where a post's readers came from: sources, categories and devices.",
+    details=(
+        "Returns the Traffic part of a post's stats: each source (app, email, a website, search) with its "
+        "views, share of all views and the free and paid subscribers it brought, the share per source "
+        "category and per device. A post nobody has read yet returns empty lists."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /posts/{post_id}/traffic",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_post_traffic(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    answer = await call(ctx, "GET", f"{pub['base']}/api/v1/post_management/detail/{pid}/traffic")
+    return {
+        "post_id": str(pid),
+        "sources": [
+            {
+                "source": row.get("source") or row.get("name") or "",
+                "views": int(row.get("views") or 0),
+                "share": _share(row),
+                "free_signups": int(row.get("signups") or 0),
+                "paid_subscriptions": int(row.get("subscribes") or 0),
+            }
+            for row in answer.get("referrers") or []
+        ],
+        "categories": [
+            {"category": row.get("category_type") or row.get("name") or "", "share": _share(row)}
+            for row in answer.get("categories") or []
+        ],
+        "devices": [
+            {"device": row.get("device_type") or row.get("name") or "", "share": _share(row)}
+            for row in answer.get("devices") or []
+        ],
+    }
+
+
+def _share(row: dict[str, Any]) -> float:
+    return round(float(row.get("percent_of_total_views") or 0), 3)

substack_api_mcp/substack/tools/get_publication_stats.py

@@ -0,0 +1,74 @@
+"""Get publication stats."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any
+from zoneinfo import ZoneInfo
+
+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"], "description": "7d, 30d or 90d. Default: 30d."}
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "period": "7d",
+    "subscribers_total": 4380,
+    "subscribers_paid": 412,
+    "subscribers_new": 96,
+    "subscribers_churned": 11,
+    "revenue_usd": 725.48,
+}
+
+
+@tool(
+    name="get_publication_stats",
+    title="Get publication stats",
+    access="read",
+    confirm=False,
+    description="Total and paid subscribers, new subscribers, paid cancellations and estimated revenue for a period.",
+    details=(
+        "Totals are from the publisher dashboard at the end of the period (7, 30 or 90 days). "
+        "subscribers_churned counts paid cancellations only; Substack keeps no count of free unsubscribes. "
+        "subscribers_new is the growth in total subscribers plus those cancellations. revenue_usd is not "
+        "money received: it is the dashboard's annualized revenue at the end of the period, times the "
+        "period's share of a year."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /stats",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_publication_stats(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    period = args.get("period") or "30d"
+    days = int(period[:-1])
+    pub = await publication(ctx)
+    # The dashboard's summary for the last N days: subscribers and ARR at the start and the end.
+    summary = await call(ctx, "GET", f"{pub['base']}/api/v1/publish-dashboard/summary-v2", params={"range": days})
+    today = datetime.now(ZoneInfo("Europe/Warsaw")).date()
+    window = {"from": (today - timedelta(days=days)).isoformat(), "to": today.isoformat(), "offset": 0, "limit": 1}
+    # Cancelled paid subscriptions in the period (Analytics > Unsubscribes); Substack keeps no count of free ones.
+    cancels = await call(ctx, "GET", f"{pub['base']}/api/v1/publication/stats/unsubscribes", params=window)
+    churned = int(cancels.get("total") or 0)
+    total_end = int(summary.get("totalSubscribersEnd") or 0)
+    total_start = int(summary.get("totalSubscribersStart") or 0)
+    # ARR is in cents, as Substack's other money fields; revenue is the period's share of it.
+    arr = float(summary.get("arrEnd") or 0) / 100
+    return {
+        "period": period,
+        "subscribers_total": total_end,
+        "subscribers_paid": int(summary.get("paidSubscribersEnd") or 0),
+        "subscribers_new": max(total_end - total_start + churned, 0),
+        "subscribers_churned": churned,
+        "revenue_usd": round(arr * days / 365, 2),
+    }

substack_api_mcp/substack/tools/get_unread_counts.py

@@ -0,0 +1,40 @@
+"""Get unread counts."""
+
+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
+
+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] = {"messages": 2, "message_requests": 1, "activity": 7}
+
+
+@tool(
+    name="get_unread_counts",
+    title="Get unread counts",
+    access="read",
+    confirm=False,
+    description="How many unread direct messages, message requests and activity notifications you have.",
+    details=(
+        "Returns the badges of the Substack app: unread direct messages, pending message requests and unread "
+        "activity (likes, replies, new followers, restacks). Reading them marks nothing read."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /unread-counts",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def get_unread_counts(ctx: ToolContext, _args: dict[str, Any]) -> Any:
+
+    messages = await call(ctx, "GET", f"{WEB}/api/v1/messages/unread-count")
+    activity = await call(ctx, "GET", f"{WEB}/api/v1/activity/unread")
+    return {
+        "messages": int(messages.get("unreadCount") or 0),
+        "message_requests": int(messages.get("pendingInviteCount") or 0),
+        "activity": int(activity.get("count") or 0),
+    }

substack_api_mcp/substack/tools/like_comment.py

@@ -0,0 +1,57 @@
+"""Like comment."""
+
+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, comment_id, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "comment_id": {"type": "string", "description": "Comment ID from list_comments, or a Note ID."},
+        "unlike": {"type": "boolean", "description": "Remove your like instead. Default: false."},
+    },
+    "required": ["comment_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"comment_id": "364149469", "liked": True}
+
+
+@tool(
+    name="like_comment",
+    title="Like comment or Note",
+    access="write",
+    confirm=False,
+    description="Like or unlike a comment or a Note as you.",
+    details=(
+        "Adds your heart to any Note or Note reply, or to a comment under a post of your publication, or "
+        "removes it with unlike. Comments and Notes share one ID space, so a Note ID from list_notes or "
+        "search_substack works too. The author sees your like in their activity."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PUT /comments/{comment_id}/like",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def like_comment(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    cid = comment_id(args["comment_id"])
+    unlike = bool(args.get("unlike"))
+    method = "DELETE" if unlike else "POST"
+    try:
+        # Notes and their replies live on substack.com.
+        await call(ctx, method, f"{WEB}/api/v1/comment/{cid}/reaction", body={"reaction": "\u2764"})
+    except ToolError as exc:
+        if exc.code != ErrorCode.TARGET_ERROR:
+            raise
+        # A comment under a post answers only on its publication's host, as the post page sends it.
+        pub = await publication(ctx)
+        body = {"publication_id": pub["id"], "reaction": "\u2764"}
+        await call(ctx, method, f"{pub['base']}/api/v1/comment/{cid}/reaction", body=body)
+    return {"comment_id": str(cid), "liked": not unlike}

substack_api_mcp/substack/tools/like_post.py

@@ -0,0 +1,45 @@
+"""Like 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 WEB, call, post_id
+
+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 search_substack, list_posts or a post's data."},
+        "unlike": {"type": "boolean", "description": "Remove your like instead. Default: false."},
+    },
+    "required": ["post_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"post_id": "197396217", "liked": True}
+
+
+@tool(
+    name="like_post",
+    title="Like post",
+    access="write",
+    confirm=False,
+    description="Like or unlike any Substack post as you.",
+    details=(
+        "Adds your heart to a post on any publication, as the heart under a post does, or removes it with "
+        "unlike. The author sees your like in their activity. Liking twice keeps one like."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PUT /posts/{post_id}/like",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def like_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pid = post_id(args["post_id"])
+    unlike = bool(args.get("unlike"))
+    await call(ctx, "DELETE" if unlike else "POST", f"{WEB}/api/v1/post/{pid}/reaction", body={"reaction": "\u2764"})
+    return {"post_id": str(pid), "liked": not unlike}

substack_api_mcp/substack/tools/list_activity.py

@@ -0,0 +1,111 @@
+"""List activity."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+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
+
+_FILTERS = {"all": "all", "replies": "replies-and-mentions", "restacks": "restacks"}
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "filter": {
+            "type": "string",
+            "enum": ["all", "replies", "restacks"],
+            "description": "all, replies (replies and mentions) or restacks. Default: all.",
+        },
+        "cursor": {"type": "string", "description": "next_cursor from the previous page."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "activity": [
+        {
+            "type": "note_reply",
+            "at": "2026-10-18T16:35:45.367Z",
+            "from": [{"user_id": "561099060", "name": "Maya Chen", "handle": "mayachen"}],
+            "people": 1,
+            "comment_id": "364181517",
+            "text": "Rain walks are underrated. Boots or sneakers?",
+            "on_comment_id": "364181148",
+            "on_post_id": None,
+        },
+        {
+            "type": "follow",
+            "at": "2026-10-18T16:34:31.102Z",
+            "from": [{"user_id": "561099060", "name": "Maya Chen", "handle": "mayachen"}],
+            "people": 1,
+            "comment_id": None,
+            "text": None,
+            "on_comment_id": None,
+            "on_post_id": None,
+        },
+    ],
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_activity",
+    title="List activity",
+    access="read",
+    confirm=False,
+    description="Your Substack notifications: replies, likes, new followers, restacks, newest first.",
+    details=(
+        "Returns the Activity tab of the Substack app, newest first. type is Substack's own name, e.g. "
+        "note_reply, note_like, comment_reply, comment_like, post_like, follow, restack or mention. from lists "
+        "the latest people behind a grouped item and people counts all of them. A reply or mention carries "
+        "its comment_id and text; on_comment_id and on_post_id point at what it was about. Reading the list "
+        "marks nothing read. Page with next_cursor."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /activity",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_activity(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    params: dict[str, Any] = {"filter": _FILTERS[args.get("filter") or "all"]}
+    if args.get("cursor"):
+        params["after"] = args["cursor"]
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/activity-feed-web", params=params)
+    users = {user.get("id"): user for user in answer.get("users") or []}
+    texts = {
+        c.get("id"): c.get("body") for c in (answer.get("comments") or []) + (answer.get("feedItemComments") or [])
+    }
+    items = answer.get("activityItems") or []
+    activity = [
+        {
+            "type": item.get("type") or "",
+            "at": item.get("updated_at") or item.get("created_at"),
+            "from": [person(users[uid]) for uid in item.get("recent_sender_ids") or [] if uid in users],
+            "people": int(item.get("sender_count") or 0),
+            "comment_id": _id(item.get("comment_id")),
+            "text": texts.get(item.get("comment_id")) if item.get("comment_id") else None,
+            "on_comment_id": _id(item.get("target_comment_id")),
+            "on_post_id": _id(item.get("target_post_id")),
+        }
+        for item in items
+    ]
+    return {"activity": activity, "next_cursor": _cursor(items) if answer.get("more") else None}
+
+
+def _id(value: Any) -> str | None:
+    return str(value) if value else None
+
+
+def _cursor(items: list[dict[str, Any]]) -> str | None:
+    """The app pages back from the oldest item's time, one millisecond earlier."""
+    stamps = [item["updated_at"] for item in items if item.get("updated_at")]
+    if not stamps:
+        return None
+    oldest = min(datetime.fromisoformat(stamp.replace("Z", "+00:00")) for stamp in stamps)
+    return (oldest - timedelta(milliseconds=1)).isoformat(timespec="milliseconds").replace("+00:00", "Z")