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

substack_api_mcp/substack/tools/list_comments.py

@@ -0,0 +1,79 @@
+"""List comments."""
+
+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."},
+        "unanswered_only": {"type": "boolean", "description": "Skip threads you already replied to."},
+    },
+    "required": ["post_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "comments": [
+        {
+            "comment_id": "363478059",
+            "author": "Maya Chen",
+            "body": "Does the next part cover pricing?",
+            "created_at": "2026-10-07T08:20:00Z",
+            "replied": False,
+            "replies": [],
+        }
+    ]
+}
+
+
+@tool(
+    name="list_comments",
+    title="List comments",
+    access="read",
+    confirm=False,
+    description="Comments on a post, with author, text and whether you replied.",
+    details=(
+        "Returns all comments of one post at once, oldest first, with replies nested under their parent. "
+        "Deleted comments are left out. replied is true when you answered anywhere in the thread under the "
+        "comment; unanswered_only keeps only top-level comments where you did not. Pass comment_id to "
+        "reply_to_comment."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /posts/{post_id}/comments",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_comments(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    params = {"all_comments": "true", "sort": "oldest_first"}
+    answer = await call(ctx, "GET", f"{pub['base']}/api/v1/post/{pid}/comments", params=params)
+    comments = [_comment(row, pub["user_id"]) for row in answer.get("comments") or [] if not row.get("deleted")]
+    if args.get("unanswered_only"):
+        comments = [item for item in comments if not item["replied"]]
+    return {"comments": comments}
+
+
+def _comment(row: dict[str, Any], me: Any) -> dict[str, Any]:
+    children = [child for child in row.get("children") or [] if not child.get("deleted")]
+    return {
+        "comment_id": str(row["id"]),
+        "author": row.get("name") or "",
+        "body": row.get("body") or "",
+        "created_at": row.get("date"),
+        "replied": _replied(children, me),
+        "replies": [_comment(child, me) for child in children],
+    }
+
+
+def _replied(children: list[dict[str, Any]], me: Any) -> bool:
+    """Whether you answered anywhere in the thread under the comment."""
+    return any(child.get("user_id") == me or _replied(child.get("children") or [], me) for child in children)

substack_api_mcp/substack/tools/list_conversations.py

@@ -0,0 +1,78 @@
+"""List conversations."""
+
+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": {
+        "unread_only": {"type": "boolean", "description": "Only conversations with unread messages."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous page."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "conversations": [
+        {
+            "conversation_id": "112992a4-5356-4bd2-8a16-f940cabbb4df",
+            "with": "Maya Chen",
+            "last_message": "Also, what newsletter tool did you switch from?",
+            "last_from_you": True,
+            "last_at": "2026-10-18T15:55:35.587Z",
+            "unread": 0,
+            "is_request": False,
+        }
+    ],
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_conversations",
+    title="List conversations",
+    access="read",
+    confirm=False,
+    description="Your direct-message conversations, latest first, with the last message.",
+    details=(
+        "Returns your Substack chat inbox: one-to-one and group direct messages with who they are with, the "
+        "last message, its time, your unread count and whether it is a message request from someone you do "
+        "not follow. Publication chats are left out. Reading the list does not mark anything read. Pass "
+        "conversation_id to get_conversation or send_message."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /conversations",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_conversations(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    params = {"tab": "unread" if args.get("unread_only") else "all"}
+    if args.get("cursor"):
+        params["cursor"] = args["cursor"]
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/messages/inbox", params=params)
+    conversations = []
+    for row in answer.get("threads") or []:
+        thread = row.get("messageThread") or {}
+        if row.get("type") != "direct-message" or not thread.get("id"):
+            continue
+        recent = row.get("recentMessage") or {}
+        conversations.append(
+            {
+                "conversation_id": thread["id"],
+                "with": row.get("title") or thread.get("name") or "",
+                "last_message": recent.get("body") or row.get("subtitleBody") or "",
+                "last_from_you": row.get("subtitleName") == "You",
+                "last_at": row.get("timestamp") or recent.get("created_at"),
+                "unread": int(row.get("unreadCount") or 0),
+                "is_request": bool(row.get("isRequest")),
+            }
+        )
+    return {"conversations": conversations, "next_cursor": answer.get("nextCursor")}

substack_api_mcp/substack/tools/list_note_replies.py

@@ -0,0 +1,79 @@
+"""List Note replies."""
+
+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, person
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "note_id": {"type": "string", "description": "Note ID from list_notes or search_substack."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous page."},
+    },
+    "required": ["note_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "replies": [
+        {
+            "note_id": "364150283",
+            "author": {"user_id": "81309935", "name": "Sam Ortiz", "handle": ""},
+            "body": "Same here, the phone rule changed everything.",
+            "published_at": "2026-10-18T15:55:08.644Z",
+            "likes": 2,
+            "restacks": 0,
+            "replies": 1,
+            "url": None,
+        }
+    ],
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_note_replies",
+    title="List Note replies",
+    access="read",
+    confirm=False,
+    description="Replies under a Note, with author, text and likes.",
+    details=(
+        "Returns the direct replies under one Note (yours or anyone's), in Substack's order. replies is the "
+        "count under each reply; list those by passing its note_id. Substack sends no handle with replies, so "
+        "author.handle is empty and url is null. Page with next_cursor."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /notes/{note_id}/replies",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_note_replies(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    nid = comment_id(args["note_id"], "list_notes")
+    params = {"cursor": args["cursor"]} if args.get("cursor") else None
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/reader/comment/{nid}/replies", params=params)
+    replies = [
+        _note(branch["comment"])
+        for branch in answer.get("commentBranches") or []
+        if (branch.get("comment") or {}).get("id")
+    ]
+    return {"replies": replies, "next_cursor": answer.get("nextCursor")}
+
+
+def _note(comment: dict[str, Any]) -> dict[str, Any]:
+    handle = comment.get("handle") or ""
+    return {
+        "note_id": str(comment["id"]),
+        "author": person({"id": comment.get("user_id"), "name": comment.get("name"), "handle": handle}),
+        "body": comment.get("body") or "",
+        "published_at": comment.get("date"),
+        "likes": int(comment.get("reaction_count") or 0),
+        "restacks": int(comment.get("restacks") or 0),
+        "replies": int(comment.get("children_count") or 0),
+        "url": f"{WEB}/@{handle}/note/c-{comment['id']}" if handle else None,
+    }

substack_api_mcp/substack/tools/list_notes.py

@@ -0,0 +1,80 @@
+"""List Notes."""
+
+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, person, publication, 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. Default: you."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous page."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "notes": [
+        {
+            "note_id": "364150154",
+            "author": {"user_id": "561078443", "name": "Maya Chen", "handle": "mayachen"},
+            "body": "Day 21 of the early hour. Coffee first, phone last.",
+            "published_at": "2026-10-18T15:54:57.801Z",
+            "likes": 12,
+            "restacks": 1,
+            "replies": 3,
+            "url": "https://substack.com/@mayachen/note/c-364150154",
+        }
+    ],
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_notes",
+    title="List Notes",
+    access="read",
+    confirm=False,
+    description="Notes posted by you or any other Substack user, newest first, with likes and replies.",
+    details=(
+        "Returns the Notes on a profile's Notes tab, newest first: text, time, likes, restacks, reply count "
+        "and link. Without user it lists yours. Posts and restacks of posts on the profile are left out. "
+        "Page with next_cursor. Pass note_id to list_note_replies, like_comment or reply_to_note."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /notes",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_notes(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    who = await user_ref(ctx, args["user"]) if args.get("user") else {"id": (await publication(ctx))["user_id"]}
+    uid = who["id"]
+    params = {"cursor": args["cursor"]} if args.get("cursor") else None
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/reader/feed/profile/{uid}", params=params)
+    notes = [
+        _note(item["comment"])
+        for item in answer.get("items") or []
+        if item.get("type") == "comment" and (item.get("comment") or {}).get("id")
+    ]
+    return {"notes": notes, "next_cursor": answer.get("nextCursor")}
+
+
+def _note(comment: dict[str, Any]) -> dict[str, Any]:
+    handle = comment.get("handle") or ""
+    return {
+        "note_id": str(comment["id"]),
+        "author": person({"id": comment.get("user_id"), "name": comment.get("name"), "handle": handle}),
+        "body": comment.get("body") or "",
+        "published_at": comment.get("date"),
+        "likes": int(comment.get("reaction_count") or 0),
+        "restacks": int(comment.get("restacks") or 0),
+        "replies": int(comment.get("children_count") or 0),
+        "url": f"{WEB}/@{handle}/note/c-{comment['id']}" if handle else None,
+    }

substack_api_mcp/substack/tools/list_post_tags.py

@@ -0,0 +1,48 @@
+"""List post tags."""
+
+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": {}, "required": [], "additionalProperties": False}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "tags": [{"tag_id": "80ba205f-6de0-4024-860d-0df42720d32a", "name": "Habits", "slug": "habits", "hidden": False}]
+}
+
+
+@tool(
+    name="list_post_tags",
+    title="List post tags",
+    access="read",
+    confirm=False,
+    description="Tags your publication uses to group posts.",
+    details=(
+        "Returns every post tag of your publication with its ID, name and slug; readers see tagged posts on "
+        "/t/{slug}. hidden tags group posts without a public page. Pass tag_id to tag_post."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /post-tags",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_post_tags(ctx: ToolContext, _args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    rows = await call(ctx, "GET", f"{pub['base']}/api/v1/publication/post-tag")
+    return {
+        "tags": [
+            {
+                "tag_id": str(row["id"]),
+                "name": row.get("name") or "",
+                "slug": row.get("slug") or "",
+                "hidden": bool(row.get("hidden")),
+            }
+            for row in rows or []
+        ]
+    }

substack_api_mcp/substack/tools/list_posts.py

@@ -0,0 +1,105 @@
+"""List posts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.helpers import limit
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import (
+    call,
+    next_cursor,
+    offset_cursor,
+    post_status,
+    post_url,
+    publication,
+    scheduled_at,
+)
+
+# Status -> dashboard list and its order, as the Posts tabs of the dashboard ask for them.
+_LISTS = {
+    "published": ("published", "post_date", "desc"),
+    "draft": ("drafts", "draft_updated_at", "desc"),
+    "scheduled": ("scheduled", "trigger_at", "asc"),
+}
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "status": {
+            "type": "string",
+            "enum": ["published", "draft", "scheduled"],
+            "description": "published, draft or scheduled. Default: published.",
+        },
+        "limit": {"type": "integer", "description": "1 to 50. Default: 20."},
+        "cursor": {"type": "string", "description": "Next page cursor from the previous call."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "posts": [
+        {
+            "post_id": "148213977",
+            "title": "The quiet launch",
+            "status": "published",
+            "audience": "everyone",
+            "published_at": "2026-10-06T12:00:00Z",
+            "url": "https://yourname.substack.com/p/the-quiet-launch",
+        },
+        {
+            "post_id": "148420031",
+            "title": "Notes on pricing",
+            "status": "draft",
+            "audience": "only_paid",
+            "published_at": None,
+            "url": None,
+        },
+    ],
+    "next_cursor": "eyJvZmZzZXQiOjIwfQ",
+}
+
+
+@tool(
+    name="list_posts",
+    title="List posts",
+    access="read",
+    confirm=False,
+    description="Posts of your publication, newest first, with status and audience.",
+    details=(
+        "Lists posts of your publication, newest first. Filter by status to see drafts or scheduled posts. "
+        "Scheduled posts include their publish time. Pages hold up to 50 posts; pass next_cursor back as "
+        "cursor for the next page."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /posts",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_posts(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    status = args.get("status") or "published"
+    endpoint, order_by, direction = _LISTS[status]
+    wanted = limit(args, 20, 50)
+    offset = offset_cursor(args.get("cursor"))
+    params = {"offset": offset, "limit": wanted, "order_by": order_by, "order_direction": direction}
+    answer = await call(ctx, "GET", f"{pub['base']}/api/v1/post_management/{endpoint}", params=params)
+    rows = answer.get("posts") or []
+    posts = []
+    for post in rows:
+        item = {
+            "post_id": str(post["id"]),
+            "title": post.get("title") or post.get("draft_title") or "",
+            "status": post_status(post),
+            "audience": post.get("audience"),
+            "published_at": post.get("post_date") if post.get("is_published") else None,
+            "url": post_url(pub, post),
+        }
+        if item["status"] == "scheduled":
+            item["publish_at"] = scheduled_at(post)
+        posts.append(item)
+    return {"posts": posts, "next_cursor": next_cursor(offset, len(rows), wanted)}

substack_api_mcp/substack/tools/list_recommendations.py

@@ -0,0 +1,109 @@
+"""List recommendations."""
+
+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": {
+        "direction": {
+            "type": "string",
+            "enum": ["given", "received"],
+            "description": "given (publications you recommend) or received (that recommend you). Default: given.",
+        },
+        "publication_id": {
+            "type": "string",
+            "description": "Check one publication instead: does yours recommend it (given only).",
+        },
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "direction": "given",
+    "recommendations": [
+        {
+            "publication_id": "5262902",
+            "name": "Brain Health Decoded",
+            "blurb": "The best science newsletter I read.",
+            "active": True,
+            "mutual": None,
+            "since": "2026-10-18T16:35:11.246Z",
+            "subscribers_sent": 12,
+        }
+    ],
+    "counts": {"given": 1, "received": 0, "subscribers_from_recommendations": 0},
+}
+
+
+@tool(
+    name="list_recommendations",
+    title="List recommendations",
+    access="read",
+    confirm=False,
+    description="Publications you recommend, or that recommend you, with the subscribers each sent.",
+    details=(
+        "Returns Audience > Recommendations: with direction given, the publications you recommend; with "
+        "received, the ones recommending you, and whether you recommend them back (mutual). "
+        "subscribers_sent counts subscribers the recommendation brought. The table is rebuilt by Substack "
+        "in the background, so a recommendation made minutes ago may be missing while counts already "
+        "include it; publication_id checks one recommendation of yours directly."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /recommendations",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_recommendations(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    direction = args.get("direction") or "given"
+    pub = await publication(ctx)
+    base = f"{pub['base']}/api/v1/recommendations"
+    exist = await call(ctx, "GET", f"{base}/exist")
+    if args.get("publication_id"):
+        target = str(args["publication_id"]).strip()
+        found = await call(ctx, "GET", f"{base}/from/{pub['id']}/to/{target}") if target.isdigit() else {}
+        target_pub = (found or {}).get("recommendedPublication") or {}
+        rows = [{**found, "target_pub": {**target_pub, "id": target}, "is_active": True}] if found else []
+        direction = "given"
+    else:
+        rows = await _all(ctx, f"{base}/stats/{'from' if direction == 'given' else 'to'}")
+    side = "target_pub" if direction == "given" else "source_pub"
+    return {
+        "direction": direction,
+        "recommendations": [
+            {
+                "publication_id": str((row.get(side) or {}).get("id") or ""),
+                "name": (row.get(side) or {}).get("name") or "",
+                "blurb": row.get("description") or row.get("blurb"),
+                "active": bool(row.get("is_active")),
+                "mutual": row.get("is_mutual") if direction == "received" else None,
+                "since": row.get("created_at"),
+                "subscribers_sent": int(row.get("xp_signups") or 0),
+            }
+            for row in rows
+        ],
+        "counts": {
+            "given": int(exist.get("recommendingOthers") or 0),
+            "received": int(exist.get("beingRecommended") or 0),
+            "subscribers_from_recommendations": int(exist.get("totalSignups") or 0),
+        },
+    }
+
+
+async def _all(ctx: ToolContext, url: str) -> list[dict[str, Any]]:
+    """The dashboard reads the table 20 rows at a time until it has them all."""
+    rows: list[dict[str, Any]] = []
+    for offset in range(0, 1000, 20):
+        page = await call(ctx, "GET", url, params={"offset": offset, "limit": 20})
+        rows += page.get("rows") or []
+        if offset + 20 >= int(page.get("total") or 0):
+            break
+    return rows

substack_api_mcp/substack/tools/list_sections.py

@@ -0,0 +1,60 @@
+"""List sections."""
+
+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": {}, "required": [], "additionalProperties": False}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "sections": [
+        {
+            "section_id": "482783",
+            "name": "Field notes",
+            "description": "Short notes from the week.",
+            "slug": "field-notes",
+            "live": True,
+            "subscribed_by_default": True,
+        }
+    ]
+}
+
+
+@tool(
+    name="list_sections",
+    title="List sections",
+    access="read",
+    confirm=False,
+    description="Sections of your publication, the separate newsletters inside it.",
+    details=(
+        "Returns each section with its ID, name, description and slug. live is false while Substack still "
+        "sets a new section up. subscribed_by_default tells whether new subscribers get its emails. A "
+        "publication without sections returns an empty list."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /sections",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_sections(ctx: ToolContext, _args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    rows = await call(ctx, "GET", f"{pub['base']}/api/v1/publication/sections")
+    return {
+        "sections": [
+            {
+                "section_id": str(row["id"]),
+                "name": row.get("name") or "",
+                "description": row.get("description") or "",
+                "slug": row.get("slug") or "",
+                "live": bool(row.get("is_live")),
+                "subscribed_by_default": bool(row.get("is_default_on")),
+            }
+            for row in rows or []
+        ]
+    }

substack_api_mcp/substack/tools/list_subscriber_tags.py

@@ -0,0 +1,36 @@
+"""List subscriber tags."""
+
+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": {}, "required": [], "additionalProperties": False}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"tags": [{"tag_id": "9357", "name": "Early readers"}]}
+
+
+@tool(
+    name="list_subscriber_tags",
+    title="List subscriber tags",
+    access="read",
+    confirm=False,
+    description="Tags you use to group subscribers.",
+    details=(
+        "Returns the subscriber tags of your publication with their IDs, as Audience > Subscribers > Tags "
+        "shows them. Subscribers never see tags. Pass tag_id to tag_subscribers."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /subscriber-tags",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_subscriber_tags(ctx: ToolContext, _args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    answer = await call(ctx, "GET", f"{pub['base']}/api/v1/subscriber-tags")
+    return {"tags": [{"tag_id": str(row["id"]), "name": row.get("name") or ""} for row in answer.get("tags") or []]}