substack-api-mcp 1.0.6__tar.gz → 1.0.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/PKG-INFO +103 -12
  2. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/README.md +102 -11
  3. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/pyproject.toml +1 -1
  4. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/__init__.py +1 -1
  5. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/.github/workflows/ci.yml +0 -0
  6. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/.github/workflows/publish.yml +0 -0
  7. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/.gitignore +0 -0
  8. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/AGENTS.md +0 -0
  9. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/CLAUDE.md +0 -0
  10. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/LICENSE +0 -0
  11. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/assets/logo-white.svg +0 -0
  12. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/assets/logo.svg +0 -0
  13. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/add_subscribers.py +0 -0
  14. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/daily_stats.py +0 -0
  15. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/draft_from_markdown.py +0 -0
  16. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/export_subscribers.py +0 -0
  17. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/get_post.py +0 -0
  18. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/list_posts.py +0 -0
  19. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/list_subscribers.py +0 -0
  20. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/post_stats.py +0 -0
  21. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/publish_note.py +0 -0
  22. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/reply_to_comment.py +0 -0
  23. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/schedule_post.py +0 -0
  24. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/traffic_sources.py +0 -0
  25. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/unanswered_comments.py +0 -0
  26. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/examples/weekly_report.py +0 -0
  27. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/glama.json +0 -0
  28. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/mcp.json +0 -0
  29. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/api.py +0 -0
  30. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/app.py +0 -0
  31. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/cli.py +0 -0
  32. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/core/__init__.py +0 -0
  33. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/core/account_guard.py +0 -0
  34. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/core/context.py +0 -0
  35. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/core/errors.py +0 -0
  36. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/core/helpers.py +0 -0
  37. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/core/tools.py +0 -0
  38. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/mcp_context.py +0 -0
  39. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/mcp_server.py +0 -0
  40. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/runner.py +0 -0
  41. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/scripting.py +0 -0
  42. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/session.py +0 -0
  43. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/__init__.py +0 -0
  44. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/auth.py +0 -0
  45. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/client.py +0 -0
  46. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/feed.py +0 -0
  47. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/markdown.py +0 -0
  48. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/publishing.py +0 -0
  49. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/subscribers.py +0 -0
  50. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/__init__.py +0 -0
  51. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/add_subscriber.py +0 -0
  52. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/cancel_scheduled_post.py +0 -0
  53. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/create_draft.py +0 -0
  54. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/create_post_tag.py +0 -0
  55. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/create_subscriber_tag.py +0 -0
  56. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/delete_comment.py +0 -0
  57. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/delete_post.py +0 -0
  58. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/duplicate_post.py +0 -0
  59. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/export_subscribers.py +0 -0
  60. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/follow_user.py +0 -0
  61. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_audience_insights.py +0 -0
  62. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_conversation.py +0 -0
  63. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_daily_stats.py +0 -0
  64. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_feed.py +0 -0
  65. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_post.py +0 -0
  66. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_post_engagement.py +0 -0
  67. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_post_stats.py +0 -0
  68. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_post_traffic.py +0 -0
  69. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_publication_stats.py +0 -0
  70. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/get_unread_counts.py +0 -0
  71. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/like_comment.py +0 -0
  72. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/like_post.py +0 -0
  73. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_activity.py +0 -0
  74. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_comments.py +0 -0
  75. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_conversations.py +0 -0
  76. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_note_replies.py +0 -0
  77. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_notes.py +0 -0
  78. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_post_tags.py +0 -0
  79. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_posts.py +0 -0
  80. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_recommendations.py +0 -0
  81. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_sections.py +0 -0
  82. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_subscriber_tags.py +0 -0
  83. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_subscribers.py +0 -0
  84. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_subscriptions.py +0 -0
  85. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/list_traffic_sources.py +0 -0
  86. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/pin_comment.py +0 -0
  87. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/publish_note.py +0 -0
  88. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/publish_post.py +0 -0
  89. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/recommend_publication.py +0 -0
  90. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/remove_comment.py +0 -0
  91. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/remove_subscriber.py +0 -0
  92. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/reply_to_comment.py +0 -0
  93. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/reply_to_note.py +0 -0
  94. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/schedule_post.py +0 -0
  95. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/search_substack.py +0 -0
  96. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/send_message.py +0 -0
  97. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/tag_post.py +0 -0
  98. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/tag_subscribers.py +0 -0
  99. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/unpublish_post.py +0 -0
  100. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/substack_api_mcp/substack/tools/update_draft.py +0 -0
  101. {substack_api_mcp-1.0.6 → substack_api_mcp-1.0.7}/uv.lock +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: substack-api-mcp
3
- Version: 1.0.6
3
+ Version: 1.0.7
4
4
  Summary: Self-hosted Substack API and MCP server on your own Chrome session. Use Substack from Claude, Cursor, Codex or any MCP client or AI agent.
5
5
  Project-URL: Homepage, https://cotlet.dev/integrations/substack-api-mcp-server
6
6
  Project-URL: Source, https://github.com/cotletdev/substack-api-mcp-server
@@ -19,13 +19,13 @@ Requires-Dist: uvicorn>=0.30
19
19
  Requires-Dist: websockets>=13
20
20
  Description-Content-Type: text/markdown
21
21
 
22
- # Substack API and MCP server: connect Substack to ChatGPT and Claude
22
+ # Substack API integration and MCP server: connect Substack to ChatGPT and Claude
23
23
 
24
24
  <!-- mcp-name: dev.cotlet/substack -->
25
25
 
26
26
  **Yes, ChatGPT, Claude and other AI agents can work in your Substack account.** That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI drafts posts from your notes, schedules them, posts Notes, answers comments and reports your subscriber and post stats. It shows you what it will do first and sends nothing to other people until you say so.
27
27
 
28
- This repo is the missing piece: 50 Substack tools for AI assistants and scripts.
28
+ As of November 2026, this repo is the missing piece: 50 Substack tools for AI assistants and scripts.
29
29
 
30
30
  ## What you can ask
31
31
 
@@ -43,12 +43,63 @@ This repo is the missing piece: 50 Substack tools for AI assistants and scripts.
43
43
  |---|---|---|
44
44
  | For | writers and publishers | developers |
45
45
  | Setup | sign in to Substack once, about 5 minutes, nothing to install | Python and a terminal |
46
- | Works in | ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, REST API | Claude Code, Claude Desktop, Cursor, Codex on your computer |
46
+ | Works in | ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, your own API endpoints (Custom API) | Claude Code, Claude Desktop, Cursor, Codex on your computer |
47
47
  | Runs | 24/7, your computer can be off | while your computer is on |
48
48
  | Price | 7 days free, no card | free |
49
49
 
50
+ Cotlet is best for writers and publishers who want ChatGPT, Claude or another AI agent to work in Substack for them, with nothing to install.
51
+
50
52
  **[Start free at cotlet.dev →](https://cotlet.dev/signup?app=substack&utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=top-button)**
51
53
 
54
+ ## What writers ask their AI to do in Substack
55
+
56
+ | Job | Ask your AI | Make it repeat |
57
+ |---|---|---|
58
+ | Draft from a Google Doc | "Turn this Google Doc into a Substack draft with its headings and images. Do not publish." | When a post is ready |
59
+ | Old posts into Substack | "Copy my archived posts from these Google Docs into Substack drafts, one per post, with the images." | Once |
60
+ | Website signups into Substack | "Add the people who signed up on my website form today as free subscribers. Show me the list first." | Your own endpoint, called from your form tool |
61
+ | Subscribers to MailerLite or Kit | "List this week's new free and paid subscribers so I can add them to MailerLite." | Your own endpoint, called from Zapier, Make or n8n |
62
+ | Notes from your post | "Write 5 Notes from my latest post and show them to me. Post the one I pick at the time I choose." | After each post |
63
+ | Why the numbers moved | "Why did my open rate drop this month? Compare opens, new subscribers and traffic sources with last month." | Monthly |
64
+ | Stats in a spreadsheet | "Put each post's opens, views and new subscribers from this year in a spreadsheet." | Your own endpoint, called from Google Sheets |
65
+ | Comments you have not answered | "List comments on my last 3 posts that I have not answered and draft a reply for each. Post nothing." | When you ask |
66
+ | Share a post on social | "Write a LinkedIn post and an X post for today's Substack post, with its link." | After each post |
67
+ | Clean up the list | "Tag subscribers with the lowest activity rating as inactive. Show me how many first." | Monthly |
68
+ | Backup | "Download my subscriber list and all my posts as a backup." | Monthly |
69
+ | Leaving Substack | "Export my posts and my subscribers with their plan for my move to Ghost." | Once |
70
+
71
+ Your AI asks you before it publishes, posts a Note, replies or changes anything. It does not auto-reply and does not post in bulk: Substack's Terms of Use forbid auto-responders and spam. Payments stay in your hands: Cotlet refuses payments.
72
+
73
+ ## Your own Substack API, built with Cotlet (hosted)
74
+
75
+ Substack gives you no API for posts, drafts or subscribers. With Cotlet you build your own: your AI does the job once in your Cloud Browser, you save it as an endpoint, and you call it from Google Sheets, Webflow or WordPress forms, Zapier, Make, n8n, your own code.
76
+
77
+ Examples you can build in a few minutes (none of them exists until you build it):
78
+
79
+ | Endpoint you build | What it returns or does |
80
+ |---|---|
81
+ | `new-subscribers` | subscribers who joined since a date, with free or paid plan |
82
+ | `add-subscriber` | adds one email to your list as a free subscriber (writes only after you allow it) |
83
+ | `post-stats` | opens, open rate, views and new subscribers per post for a period |
84
+ | `publication-stats` | total and paid subscribers, cancellations and estimated revenue for a period |
85
+ | `traffic-sources` | where your visitors came from in a period |
86
+ | `unanswered-comments` | comments on your posts that have no reply from you |
87
+ | `export-subscribers` | the full subscriber list as a CSV link |
88
+ | `create-draft` | a draft from your Markdown or HTML; nothing is sent (writes only after you allow it) |
89
+
90
+ Call it with your Cotlet API key, JSON in and JSON out:
91
+
92
+ ```bash
93
+ curl -X POST https://cotlet.dev/api/v1/custom/new-subscribers \
94
+ -H "Authorization: Bearer $COTLET_API_KEY" -H "Content-Type: application/json" -d '{}'
95
+ ```
96
+
97
+ Limits: one call runs up to 90 seconds, writes wait for your consent, payments are blocked. Start here: https://cotlet.dev/app/custom-api/new?app=substack
98
+
99
+ ## Find it on Cotlet.dev
100
+
101
+ - [Substack MCP server on Cotlet.dev](https://cotlet.dev/integrations/substack-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=old-repo)
102
+
52
103
  ## Run it yourself
53
104
 
54
105
  A **Substack API** and a **Substack MCP server** you run on your own computer, in Python, on the session of your own Google Chrome. All 50 Substack tools we run in production at [Cotlet](https://cotlet.dev/integrations/substack-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=intro): posts and drafts from Markdown, publishing and scheduling, Notes, comments, subscribers, stats, recommendations and direct messages.
@@ -56,7 +107,7 @@ A **Substack API** and a **Substack MCP server** you run on your own computer, i
56
107
  Substack has no public API to write posts, publish Notes or manage subscribers, and no official MCP server. This repo gives you both:
57
108
 
58
109
  - **MCP server** for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. [Setup](#mcp-server)
59
- - **REST API** on `http://127.0.0.1:8787/api/v1/substack`, with OpenAPI docs at `/docs`. [Setup](#rest-api)
110
+ - **REST API** on `http://127.0.0.1:8787/api/v1/substack`, with OpenAPI docs at `/docs`. [Setup](#rest-api-local-this-repo)
60
111
  - **Python**: `call("list_posts", status="draft")`, plus 14 ready scripts in [`examples/`](https://github.com/cotletdev/substack-api-mcp-server/blob/main/examples/).
61
112
 
62
113
  Free for your own use, your own business included ([license](#license)).
@@ -66,6 +117,8 @@ Free for your own use, your own business included ([license](#license)).
66
117
  [![License: Elastic 2.0](https://img.shields.io/badge/license-Elastic%202.0-141318)](https://github.com/cotletdev/substack-api-mcp-server/blob/main/LICENSE)
67
118
  [![MCP Badge](https://lobehub.com/badge/mcp/cotletdev-substack-api-mcp-server)](https://lobehub.com/mcp/cotletdev-substack-api-mcp-server)
68
119
 
120
+ Also on Odel: https://odel.app/modules/cotlet/substack and mcpbeat: https://mcpbeat.com/mcp-servers/cotlet/substack/
121
+
69
122
  ```bash
70
123
  uv tool install substack-api-mcp # or: pip install substack-api-mcp
71
124
  substack-mcp connect # reads your Substack session from Chrome
@@ -81,7 +134,7 @@ claude mcp add substack -- uvx substack-api-mcp mcp
81
134
  - [Install](#install)
82
135
  - [Connect your Chrome](#connect-your-chrome)
83
136
  - [MCP server](#mcp-server)
84
- - [REST API](#rest-api)
137
+ - [REST API](#rest-api-local-this-repo)
85
138
  - [Python and the example scripts](#python-and-the-example-scripts)
86
139
  - [All 50 tools](#all-50-tools)
87
140
  - [Configuration](#configuration)
@@ -94,14 +147,52 @@ claude mcp add substack -- uvx substack-api-mcp mcp
94
147
  ## Questions from Substack users
95
148
 
96
149
  **Does Substack have an API?**
97
- Only a limited one (checked 11 Oct 2026). Its Developer API looks up public creator profiles after approval, and there is no public API to write posts or Notes, manage subscribers or send email. RSS reads public posts only. This repo and [Cotlet](https://cotlet.dev/integrations/substack-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=faq-api) give you 50 Substack tools as a REST API and an MCP server.
150
+
151
+ A narrow one. The Substack Developer API (terms updated 8 Jan 2026) returns public creator profile data after approval. It has no endpoints for posts, drafts or subscribers. With Cotlet you build your own endpoints that work in your signed-in Substack account.
152
+
153
+ **Is there an official Substack MCP server for ChatGPT or Claude?**
154
+
155
+ Yes, read-only. Substack's MCP server reads stats, traffic, revenue and retention, only for Bestseller publications where you are an admin. It cannot publish posts or send Notes. Cotlet works in your own Substack account on any plan and also does the writing side, after your OK.
156
+
157
+ **How do I connect Substack to Zapier or Make so a website signup is added to Substack?**
158
+
159
+ Substack has no Zapier or Make app. Build an `add-subscriber` endpoint with Cotlet and call it from Zapier, Make, n8n or your form tool. Each new email is added as a free subscriber.
160
+
161
+ **How do I sync Substack subscribers to MailerLite, Kit or beehiiv without exporting a CSV every time?**
162
+
163
+ Build a `new-subscribers` endpoint and call it from Zapier, Make or n8n on a schedule. It returns the people who joined since a date, with their free or paid plan, ready to add in your email tool.
164
+
165
+ **Can Claude or ChatGPT create a draft in Substack from a Google Doc?**
166
+
167
+ Yes, with Cotlet. Your AI reads the doc and saves a Substack draft with its headings and images. Nothing is published until you say so.
168
+
169
+ **Can AI write and schedule Substack Notes?**
170
+
171
+ It writes Notes from your post and posts the one you pick, now or at the time you choose. It does not post Notes on its own.
172
+
173
+ **Can AI tell me why my open rate or subscriber growth dropped?**
174
+
175
+ Yes. It reads your post stats, daily stats and traffic sources in your account and compares two periods in plain words.
176
+
177
+ **How do I export all my Substack posts and subscribers?**
178
+
179
+ Substack exports them by hand in Settings. Your AI can download the subscriber CSV and your posts for you, and a monthly backup can run from your own endpoint.
180
+
181
+ **Can I connect Substack to Google Sheets?**
182
+
183
+ Yes. Build a `post-stats` or `publication-stats` endpoint and call it from Google Sheets, or from a Zapier or Make step that writes the rows.
184
+
185
+ **Can I move my subscribers to Ghost, beehiiv or Kit?**
186
+
187
+ Your AI exports your posts and the subscriber list with each person's plan, in the files those importers take. Stripe and paid subscriptions stay in your hands.
188
+
189
+ **Is this allowed by Substack's terms?**
190
+
191
+ Cotlet works in your own signed-in Substack session and does what you ask, one task at a time, with your OK before anything is posted. Substack's Terms of Use (6 Oct 2026) forbid auto-responders, spam and crawling, so do not use it for auto-replies, bulk Notes or copying other writers' posts.
98
192
 
99
193
  **Can I get a Substack API key?**
100
194
  Not from Substack for your own account. With Cotlet you get your own API key that works with your Substack account, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own Substack session.
101
195
 
102
- **Is there an official ChatGPT integration for Substack?**
103
- Partly. Substack has an official Claude connector that reads your publication's data, such as subscribers, revenue and post stats. It cannot write. Cotlet adds the writing side: drafts, publishing and scheduling, Notes, comments and messages, in ChatGPT, Claude and other AI agents.
104
-
105
196
  **How do I connect Substack to ChatGPT?**
106
197
  Sign up at [cotlet.dev](https://cotlet.dev/signup?app=substack&utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=faq-chatgpt), sign in to Substack once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your Substack like you would ask an assistant. ChatGPT needs a server on the internet, so this repo alone, running on your computer, does not connect to ChatGPT.
107
198
 
@@ -296,7 +387,7 @@ Then ask your agent things like:
296
387
  >
297
388
  > *Where did my readers come from in the last 30 days?*
298
389
 
299
- ## REST API
390
+ ## REST API (local, this repo)
300
391
 
301
392
  ```bash
302
393
  substack-mcp serve # http://127.0.0.1:8787, MCP at /mcp, docs at /docs
@@ -516,7 +607,7 @@ The REST API answers `{"error": "<code>", "message": "..."}`. The MCP server ret
516
607
  | Substack session | your Chrome, cookies in a local file | your own Cloud Browser in the EU, profile encrypted with AES-256-GCM |
517
608
  | When Substack changes its site | `git pull` once we have fixed it | fixed for you, every tool tested daily |
518
609
  | Approvals | your MCP client asks per call | posts, Notes, replies and DMs wait for your OK, switchable per tool |
519
- | Works with | MCP clients on your machine, local scripts | Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client |
610
+ | Works with | MCP clients on your machine, local scripts | Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client through your own endpoints (Custom API) |
520
611
  | Who may use it | you and your own business | you, teams, businesses, agencies |
521
612
  | Price | free | free 7-day trial with 2,000 credits, no card; then one-time packs from $29 for 5,000 credits |
522
613
 
@@ -1,10 +1,10 @@
1
- # Substack API and MCP server: connect Substack to ChatGPT and Claude
1
+ # Substack API integration and MCP server: connect Substack to ChatGPT and Claude
2
2
 
3
3
  <!-- mcp-name: dev.cotlet/substack -->
4
4
 
5
5
  **Yes, ChatGPT, Claude and other AI agents can work in your Substack account.** That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI drafts posts from your notes, schedules them, posts Notes, answers comments and reports your subscriber and post stats. It shows you what it will do first and sends nothing to other people until you say so.
6
6
 
7
- This repo is the missing piece: 50 Substack tools for AI assistants and scripts.
7
+ As of November 2026, this repo is the missing piece: 50 Substack tools for AI assistants and scripts.
8
8
 
9
9
  ## What you can ask
10
10
 
@@ -22,12 +22,63 @@ This repo is the missing piece: 50 Substack tools for AI assistants and scripts.
22
22
  |---|---|---|
23
23
  | For | writers and publishers | developers |
24
24
  | Setup | sign in to Substack once, about 5 minutes, nothing to install | Python and a terminal |
25
- | Works in | ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, REST API | Claude Code, Claude Desktop, Cursor, Codex on your computer |
25
+ | Works in | ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, your own API endpoints (Custom API) | Claude Code, Claude Desktop, Cursor, Codex on your computer |
26
26
  | Runs | 24/7, your computer can be off | while your computer is on |
27
27
  | Price | 7 days free, no card | free |
28
28
 
29
+ Cotlet is best for writers and publishers who want ChatGPT, Claude or another AI agent to work in Substack for them, with nothing to install.
30
+
29
31
  **[Start free at cotlet.dev →](https://cotlet.dev/signup?app=substack&utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=top-button)**
30
32
 
33
+ ## What writers ask their AI to do in Substack
34
+
35
+ | Job | Ask your AI | Make it repeat |
36
+ |---|---|---|
37
+ | Draft from a Google Doc | "Turn this Google Doc into a Substack draft with its headings and images. Do not publish." | When a post is ready |
38
+ | Old posts into Substack | "Copy my archived posts from these Google Docs into Substack drafts, one per post, with the images." | Once |
39
+ | Website signups into Substack | "Add the people who signed up on my website form today as free subscribers. Show me the list first." | Your own endpoint, called from your form tool |
40
+ | Subscribers to MailerLite or Kit | "List this week's new free and paid subscribers so I can add them to MailerLite." | Your own endpoint, called from Zapier, Make or n8n |
41
+ | Notes from your post | "Write 5 Notes from my latest post and show them to me. Post the one I pick at the time I choose." | After each post |
42
+ | Why the numbers moved | "Why did my open rate drop this month? Compare opens, new subscribers and traffic sources with last month." | Monthly |
43
+ | Stats in a spreadsheet | "Put each post's opens, views and new subscribers from this year in a spreadsheet." | Your own endpoint, called from Google Sheets |
44
+ | Comments you have not answered | "List comments on my last 3 posts that I have not answered and draft a reply for each. Post nothing." | When you ask |
45
+ | Share a post on social | "Write a LinkedIn post and an X post for today's Substack post, with its link." | After each post |
46
+ | Clean up the list | "Tag subscribers with the lowest activity rating as inactive. Show me how many first." | Monthly |
47
+ | Backup | "Download my subscriber list and all my posts as a backup." | Monthly |
48
+ | Leaving Substack | "Export my posts and my subscribers with their plan for my move to Ghost." | Once |
49
+
50
+ Your AI asks you before it publishes, posts a Note, replies or changes anything. It does not auto-reply and does not post in bulk: Substack's Terms of Use forbid auto-responders and spam. Payments stay in your hands: Cotlet refuses payments.
51
+
52
+ ## Your own Substack API, built with Cotlet (hosted)
53
+
54
+ Substack gives you no API for posts, drafts or subscribers. With Cotlet you build your own: your AI does the job once in your Cloud Browser, you save it as an endpoint, and you call it from Google Sheets, Webflow or WordPress forms, Zapier, Make, n8n, your own code.
55
+
56
+ Examples you can build in a few minutes (none of them exists until you build it):
57
+
58
+ | Endpoint you build | What it returns or does |
59
+ |---|---|
60
+ | `new-subscribers` | subscribers who joined since a date, with free or paid plan |
61
+ | `add-subscriber` | adds one email to your list as a free subscriber (writes only after you allow it) |
62
+ | `post-stats` | opens, open rate, views and new subscribers per post for a period |
63
+ | `publication-stats` | total and paid subscribers, cancellations and estimated revenue for a period |
64
+ | `traffic-sources` | where your visitors came from in a period |
65
+ | `unanswered-comments` | comments on your posts that have no reply from you |
66
+ | `export-subscribers` | the full subscriber list as a CSV link |
67
+ | `create-draft` | a draft from your Markdown or HTML; nothing is sent (writes only after you allow it) |
68
+
69
+ Call it with your Cotlet API key, JSON in and JSON out:
70
+
71
+ ```bash
72
+ curl -X POST https://cotlet.dev/api/v1/custom/new-subscribers \
73
+ -H "Authorization: Bearer $COTLET_API_KEY" -H "Content-Type: application/json" -d '{}'
74
+ ```
75
+
76
+ Limits: one call runs up to 90 seconds, writes wait for your consent, payments are blocked. Start here: https://cotlet.dev/app/custom-api/new?app=substack
77
+
78
+ ## Find it on Cotlet.dev
79
+
80
+ - [Substack MCP server on Cotlet.dev](https://cotlet.dev/integrations/substack-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=old-repo)
81
+
31
82
  ## Run it yourself
32
83
 
33
84
  A **Substack API** and a **Substack MCP server** you run on your own computer, in Python, on the session of your own Google Chrome. All 50 Substack tools we run in production at [Cotlet](https://cotlet.dev/integrations/substack-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=intro): posts and drafts from Markdown, publishing and scheduling, Notes, comments, subscribers, stats, recommendations and direct messages.
@@ -35,7 +86,7 @@ A **Substack API** and a **Substack MCP server** you run on your own computer, i
35
86
  Substack has no public API to write posts, publish Notes or manage subscribers, and no official MCP server. This repo gives you both:
36
87
 
37
88
  - **MCP server** for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. [Setup](#mcp-server)
38
- - **REST API** on `http://127.0.0.1:8787/api/v1/substack`, with OpenAPI docs at `/docs`. [Setup](#rest-api)
89
+ - **REST API** on `http://127.0.0.1:8787/api/v1/substack`, with OpenAPI docs at `/docs`. [Setup](#rest-api-local-this-repo)
39
90
  - **Python**: `call("list_posts", status="draft")`, plus 14 ready scripts in [`examples/`](https://github.com/cotletdev/substack-api-mcp-server/blob/main/examples/).
40
91
 
41
92
  Free for your own use, your own business included ([license](#license)).
@@ -45,6 +96,8 @@ Free for your own use, your own business included ([license](#license)).
45
96
  [![License: Elastic 2.0](https://img.shields.io/badge/license-Elastic%202.0-141318)](https://github.com/cotletdev/substack-api-mcp-server/blob/main/LICENSE)
46
97
  [![MCP Badge](https://lobehub.com/badge/mcp/cotletdev-substack-api-mcp-server)](https://lobehub.com/mcp/cotletdev-substack-api-mcp-server)
47
98
 
99
+ Also on Odel: https://odel.app/modules/cotlet/substack and mcpbeat: https://mcpbeat.com/mcp-servers/cotlet/substack/
100
+
48
101
  ```bash
49
102
  uv tool install substack-api-mcp # or: pip install substack-api-mcp
50
103
  substack-mcp connect # reads your Substack session from Chrome
@@ -60,7 +113,7 @@ claude mcp add substack -- uvx substack-api-mcp mcp
60
113
  - [Install](#install)
61
114
  - [Connect your Chrome](#connect-your-chrome)
62
115
  - [MCP server](#mcp-server)
63
- - [REST API](#rest-api)
116
+ - [REST API](#rest-api-local-this-repo)
64
117
  - [Python and the example scripts](#python-and-the-example-scripts)
65
118
  - [All 50 tools](#all-50-tools)
66
119
  - [Configuration](#configuration)
@@ -73,14 +126,52 @@ claude mcp add substack -- uvx substack-api-mcp mcp
73
126
  ## Questions from Substack users
74
127
 
75
128
  **Does Substack have an API?**
76
- Only a limited one (checked 11 Oct 2026). Its Developer API looks up public creator profiles after approval, and there is no public API to write posts or Notes, manage subscribers or send email. RSS reads public posts only. This repo and [Cotlet](https://cotlet.dev/integrations/substack-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=faq-api) give you 50 Substack tools as a REST API and an MCP server.
129
+
130
+ A narrow one. The Substack Developer API (terms updated 8 Jan 2026) returns public creator profile data after approval. It has no endpoints for posts, drafts or subscribers. With Cotlet you build your own endpoints that work in your signed-in Substack account.
131
+
132
+ **Is there an official Substack MCP server for ChatGPT or Claude?**
133
+
134
+ Yes, read-only. Substack's MCP server reads stats, traffic, revenue and retention, only for Bestseller publications where you are an admin. It cannot publish posts or send Notes. Cotlet works in your own Substack account on any plan and also does the writing side, after your OK.
135
+
136
+ **How do I connect Substack to Zapier or Make so a website signup is added to Substack?**
137
+
138
+ Substack has no Zapier or Make app. Build an `add-subscriber` endpoint with Cotlet and call it from Zapier, Make, n8n or your form tool. Each new email is added as a free subscriber.
139
+
140
+ **How do I sync Substack subscribers to MailerLite, Kit or beehiiv without exporting a CSV every time?**
141
+
142
+ Build a `new-subscribers` endpoint and call it from Zapier, Make or n8n on a schedule. It returns the people who joined since a date, with their free or paid plan, ready to add in your email tool.
143
+
144
+ **Can Claude or ChatGPT create a draft in Substack from a Google Doc?**
145
+
146
+ Yes, with Cotlet. Your AI reads the doc and saves a Substack draft with its headings and images. Nothing is published until you say so.
147
+
148
+ **Can AI write and schedule Substack Notes?**
149
+
150
+ It writes Notes from your post and posts the one you pick, now or at the time you choose. It does not post Notes on its own.
151
+
152
+ **Can AI tell me why my open rate or subscriber growth dropped?**
153
+
154
+ Yes. It reads your post stats, daily stats and traffic sources in your account and compares two periods in plain words.
155
+
156
+ **How do I export all my Substack posts and subscribers?**
157
+
158
+ Substack exports them by hand in Settings. Your AI can download the subscriber CSV and your posts for you, and a monthly backup can run from your own endpoint.
159
+
160
+ **Can I connect Substack to Google Sheets?**
161
+
162
+ Yes. Build a `post-stats` or `publication-stats` endpoint and call it from Google Sheets, or from a Zapier or Make step that writes the rows.
163
+
164
+ **Can I move my subscribers to Ghost, beehiiv or Kit?**
165
+
166
+ Your AI exports your posts and the subscriber list with each person's plan, in the files those importers take. Stripe and paid subscriptions stay in your hands.
167
+
168
+ **Is this allowed by Substack's terms?**
169
+
170
+ Cotlet works in your own signed-in Substack session and does what you ask, one task at a time, with your OK before anything is posted. Substack's Terms of Use (6 Oct 2026) forbid auto-responders, spam and crawling, so do not use it for auto-replies, bulk Notes or copying other writers' posts.
77
171
 
78
172
  **Can I get a Substack API key?**
79
173
  Not from Substack for your own account. With Cotlet you get your own API key that works with your Substack account, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own Substack session.
80
174
 
81
- **Is there an official ChatGPT integration for Substack?**
82
- Partly. Substack has an official Claude connector that reads your publication's data, such as subscribers, revenue and post stats. It cannot write. Cotlet adds the writing side: drafts, publishing and scheduling, Notes, comments and messages, in ChatGPT, Claude and other AI agents.
83
-
84
175
  **How do I connect Substack to ChatGPT?**
85
176
  Sign up at [cotlet.dev](https://cotlet.dev/signup?app=substack&utm_source=github&utm_medium=readme&utm_campaign=substack&utm_content=faq-chatgpt), sign in to Substack once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your Substack like you would ask an assistant. ChatGPT needs a server on the internet, so this repo alone, running on your computer, does not connect to ChatGPT.
86
177
 
@@ -275,7 +366,7 @@ Then ask your agent things like:
275
366
  >
276
367
  > *Where did my readers come from in the last 30 days?*
277
368
 
278
- ## REST API
369
+ ## REST API (local, this repo)
279
370
 
280
371
  ```bash
281
372
  substack-mcp serve # http://127.0.0.1:8787, MCP at /mcp, docs at /docs
@@ -495,7 +586,7 @@ The REST API answers `{"error": "<code>", "message": "..."}`. The MCP server ret
495
586
  | Substack session | your Chrome, cookies in a local file | your own Cloud Browser in the EU, profile encrypted with AES-256-GCM |
496
587
  | When Substack changes its site | `git pull` once we have fixed it | fixed for you, every tool tested daily |
497
588
  | Approvals | your MCP client asks per call | posts, Notes, replies and DMs wait for your OK, switchable per tool |
498
- | Works with | MCP clients on your machine, local scripts | Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client |
589
+ | Works with | MCP clients on your machine, local scripts | Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client through your own endpoints (Custom API) |
499
590
  | Who may use it | you and your own business | you, teams, businesses, agencies |
500
591
  | Price | free | free 7-day trial with 2,000 credits, no card; then one-time packs from $29 for 5,000 credits |
501
592
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "substack-api-mcp"
3
- version = "1.0.6"
3
+ version = "1.0.7"
4
4
  description = "Self-hosted Substack API and MCP server on your own Chrome session. Use Substack from Claude, Cursor, Codex or any MCP client or AI agent."
5
5
  readme = "README.md"
6
6
  license = "Elastic-2.0"
@@ -11,7 +11,7 @@ from __future__ import annotations
11
11
  import asyncio
12
12
  from typing import Any
13
13
 
14
- __version__ = "1.0.6"
14
+ __version__ = "1.0.7"
15
15
 
16
16
 
17
17
  def call(tool: str, args: dict[str, Any] | None = None, **kwargs: Any) -> Any: