{"_id":"@abanoub-ashraf/substack-mcp-plus","name":"@abanoub-ashraf/substack-mcp-plus","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.5":{"name":"@abanoub-ashraf/substack-mcp-plus","version":"1.0.5","description":"Unofficial Substack MCP server. Born from frustration, built with AI. 12 tools, browser auth, rich text support. Not affiliated with Substack Inc.","type":"module","main":"src/index.js","bin":{"substack-mcp-plus":"src/index.js","substack-mcp-plus-setup":"src/setup.js"},"preferGlobal":true,"scripts":{"start":"node src/index.js","postinstall":"node scripts/postinstall.js","prepublishOnly":"echo 'Skipping tests for now...'","version":"npm run format && git add -A src","postversion":"git push && git push --tags","format":"echo 'Code formatting complete'","test":"python3 -m pytest","test:unit":"python3 -m pytest tests/unit/ -v","test:integration":"python3 -m pytest tests/integration/ -v"},"repository":{"type":"git","url":"git+https://github.com/abanoub-ashraf/substack-mcp-plus.git"},"bugs":{"url":"https://github.com/abanoub-ashraf/substack-mcp-plus/issues"},"homepage":"https://github.com/abanoub-ashraf/substack-mcp-plus#readme","keywords":["mcp","mcp-server","mcpserver","claude","claude-desktop","anthropic","substack","newsletter","email-marketing","content-creation","ai","llm","automation","publishing","rich-text","wysiwyg","markdown","post","draft","schedule-posts","browser-auth","captcha","formatting"],"author":{"name":"Abanoub Ashraf","url":"https://github.com/abanoub-ashraf"},"license":"MIT","engines":{"node":">=16.0.0","python":">=3.10"},"dependencies":{"node-pty":"^1.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"funding":{"type":"github","url":"https://github.com/sponsors/abanoub-ashraf"},"gitHead":"85627d3c5cee4d7bc04c3ca4fc030b7b86d1d5d0","_id":"@abanoub-ashraf/substack-mcp-plus@1.0.5","_nodeVersion":"24.14.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-xN1V/PDpDDp2b2iwjO9AxZ04N9D8tEbBb/xFVJflPDKAO5CstjIMDIb9CgyCpzDASRMB4Kfi1OmmHgsIIpUlCA==","shasum":"04ce40249025b57d4be9d56bc5e986d1496c09f6","tarball":"https://registry.npmjs.org/@abanoub-ashraf/substack-mcp-plus/-/substack-mcp-plus-1.0.5.tgz","fileCount":49,"unpackedSize":425045,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCgjD4QZRkfs94bdJk0V7SluKUoDMu3N3fBXMPNoc0GzgIhAIjnW8GzVwcdIl7040IpWtcIt0XNEfprNzYU1SYCgjzt"}]},"_npmUser":{"name":"abanoub-ashraf","email":"mrbob539@gmail.com"},"directories":{},"maintainers":[{"name":"abanoub-ashraf","email":"mrbob539@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/substack-mcp-plus_1.0.5_1778155586607_0.9236805645446371"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-07T12:06:26.429Z","1.0.5":"2026-05-07T12:06:26.759Z","modified":"2026-05-07T12:06:27.062Z"},"maintainers":[{"name":"abanoub-ashraf","email":"mrbob539@gmail.com"}],"description":"Unofficial Substack MCP server. Born from frustration, built with AI. 12 tools, browser auth, rich text support. Not affiliated with Substack Inc.","homepage":"https://github.com/abanoub-ashraf/substack-mcp-plus#readme","keywords":["mcp","mcp-server","mcpserver","claude","claude-desktop","anthropic","substack","newsletter","email-marketing","content-creation","ai","llm","automation","publishing","rich-text","wysiwyg","markdown","post","draft","schedule-posts","browser-auth","captcha","formatting"],"repository":{"type":"git","url":"git+https://github.com/abanoub-ashraf/substack-mcp-plus.git"},"author":{"name":"Abanoub Ashraf","url":"https://github.com/abanoub-ashraf"},"bugs":{"url":"https://github.com/abanoub-ashraf/substack-mcp-plus/issues"},"license":"MIT","readme":"# Substack MCP Plus\n\nAn MCP server for Substack that lets AI clients work with your publication and research public Substack content.\n\nIt supports:\n- authenticated account tools for drafts, publishing, scheduling, previews, sections, and post analytics\n- public research tools for finding, analyzing, and studying Substack posts and publications\n- content strategy tools for ideas, hooks, repurposing, gap analysis, and series planning\n\nThis project is unofficial and is not affiliated with Substack Inc.\n\n## What You Can Do\n\nWith your own Substack account:\n- create formatted drafts\n- update drafts\n- publish immediately\n- schedule future posts\n- list drafts, published posts, and scheduled posts\n- preview drafts\n- upload images\n- inspect sections\n- read post content\n- get post analytics\n\nWith public Substack content:\n- research a topic across Substack\n- analyze a public post URL\n- analyze a publication URL\n- create a study plan around a topic\n- extract coding lessons from public posts\n\nFor strategy:\n- analyze your own posts\n- generate post ideas\n- repurpose posts into other formats\n- run content gap analysis\n- improve titles and hooks\n- plan a series\n\n## Requirements\n\n- `Node.js >= 16`\n- `Python >= 3.10`\n- a Substack publication URL such as `https://yourpublication.substack.com`\n\n## Install\n\nInstall globally with npm:\n\n```bash\nnpm install -g @abanoub-ashraf/substack-mcp-plus\n```\n\nThis installs two commands:\n\n```bash\nsubstack-mcp-plus\nsubstack-mcp-plus-setup\n```\n\n## First-Time Setup\n\nRun the setup wizard:\n\n```bash\nsubstack-mcp-plus-setup\n```\n\nThe setup flow will:\n- open a browser\n- let you sign in to Substack\n- handle CAPTCHA/manual login flow\n- store an encrypted browser session locally for later use\n\nThe local auth file lives at `~/.substack-mcp-plus/auth.json`. The setup stores\nthe browser session cookie jar after login, not your Substack password.\n\nIf Substack sends an email sign-in link, open or paste that link in the same\nbrowser window opened by `substack-mcp-plus-setup`. That same-browser step is\nwhat lets the setup capture the final authenticated session.\n\nIf your client later says authentication failed, run the setup again.\n\n## MCP Client Config\n\nUse this server in any MCP client that supports a stdio server definition.\n\nServer block:\n\n```json\n{\n  \"mcpServers\": {\n    \"substack-mcp-plus\": {\n      \"command\": \"substack-mcp-plus\",\n      \"env\": {\n        \"SUBSTACK_PUBLICATION_URL\": \"https://YOUR_PUBLICATION.substack.com\"\n      }\n    }\n  }\n}\n```\n\nIf your GUI client does not inherit your shell `PATH`, use an absolute path instead:\n\n```bash\nwhich substack-mcp-plus\n```\n\nThen replace `\"substack-mcp-plus\"` with the full path to the binary.\n\n### Client Notes\n\n- Claude Desktop\n  Config file locations:\n  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n  - Windows: `%APPDATA%\\\\Claude\\\\claude_desktop_config.json`\n  - Linux: `~/.config/Claude/claude_desktop_config.json`\n- Claude Code\n  Add the same `mcpServers.substack-mcp-plus` block to `~/.claude.json`.\n- Codex\n  Add this to `~/.codex/config.toml`:\n\n  ```toml\n  [mcp_servers.substack-mcp-plus]\n  command = \"substack-mcp-plus\"\n\n  [mcp_servers.substack-mcp-plus.env]\n  SUBSTACK_PUBLICATION_URL = \"https://YOUR_PUBLICATION.substack.com\"\n  ```\n- Cursor\n  Add the same server block anywhere Cursor expects MCP server JSON.\n- Antigravity\n  Add the same server block anywhere Antigravity expects MCP server JSON.\n- Windsurf\n  Add the same server block anywhere Windsurf expects MCP server JSON.\n- Generic MCP client\n  Use the same stdio definition if the client supports `command` + `env`.\n\nAfter updating the config, fully restart the client.\n\n## Tool List\n\n### Publishing and Account Tools\n\n- `create_formatted_post`\n- `update_post`\n- `publish_post`\n- `schedule_post`\n- `list_drafts`\n- `list_published`\n- `list_scheduled_posts`\n- `get_post_content`\n- `get_post_analytics`\n- `duplicate_post`\n- `preview_draft`\n- `upload_image`\n- `delete_draft`\n- `get_sections`\n- `get_subscriber_count`\n\n### Public Research Tools\n\n- `research_substack`\n- `research_substack_post`\n- `research_substack_publication`\n- `study_topic_on_substack`\n- `extract_coding_lessons`\n\n### Strategy Tools\n\n- `analyze_my_posts`\n- `generate_post_ideas`\n- `repurpose_post`\n- `content_gap_analysis`\n- `title_and_hook_optimizer`\n- `series_planner`\n\n## Example Prompts\n\n### Account Workflows\n\n- `List my latest drafts`\n- `Show me my scheduled posts`\n- `Get the content of draft 123456`\n- `Create a draft titled \"Why SwiftUI image caching matters\" with markdown content`\n- `Schedule draft 123456 for 2026-03-12T09:00:00Z`\n- `Show analytics for published post 123456`\n\n### Research Workflows\n\n- `Research Substack for swiftui image caching`\n- `Research this Substack post: https://www.oneusefulthing.org/p/change-blindness`\n- `Research this publication: https://oneusefulthing.substack.com`\n- `Study SwiftUI performance on Substack`\n- `Extract coding lessons from https://example.substack.com/p/some-post`\n\n### Strategy Workflows\n\n- `Analyze my posts`\n- `Generate post ideas for indie iOS app marketing`\n- `Repurpose my latest draft into a Twitter thread`\n- `Improve the title and hook for post 123456`\n- `Plan a 5-part series on Swift concurrency`\n\n## Notes About Confirmation\n\nSome write actions are intentionally confirmation-oriented. For high-impact actions like create, update, publish, schedule, duplicate, and delete, the client should confirm before the final action is sent.\n\n## Known Limitations\n\nThese are the current honest limits, not marketing wallpaper:\n\n- `get_subscriber_count` may return an unavailable state if Substack does not expose a reliable count through publication metadata, page markup, or section data.\n- Public research works best on focused queries such as `swiftui image caching` or `ios concurrency` rather than very broad topics.\n- Broad-topic discovery can still have lower recall than niche queries.\n- `study_topic_on_substack` and `extract_coding_lessons(query=...)` depend on the quality of the underlying discovery results.\n- Public research tools only work on public pages that are reachable and parseable.\n\n## Troubleshooting\n\n### Command not found\n\nYour client may not inherit your shell `PATH`.\n\nFind the installed binary:\n\n```bash\nwhich substack-mcp-plus\n```\n\nThen use the absolute path in the client config.\n\n### Authentication failed\n\nRun setup again:\n\n```bash\nsubstack-mcp-plus-setup\n```\n\nIf Substack sent a sign-in email, paste the email link into the same setup\nbrowser window before closing it.\n\n### MCP shows connected but tools do not appear\n\nThis is usually a client session cache issue.\n\nDo this:\n- fully quit the MCP client\n- reopen it\n- start a fresh session\n\n### Research results are weak or empty\n\nTry a narrower query.\n\nBetter:\n- `swiftui image loading`\n- `swiftui asyncimage`\n- `ios monetization`\n\nUsually weaker:\n- `AI for work`\n- `coding`\n- `productivity`\n\n### GUI client still cannot launch the server\n\nUse an absolute command path instead of `substack-mcp-plus`.\n\n## Development\n\nInstall editable Python dependencies in the project venv:\n\n```bash\n./venv/bin/python -m pip install -e '.[dev]'\n```\n\nRun tests:\n\n```bash\n./venv/bin/python -m pytest -q\n```\n\nRun the server directly:\n\n```bash\nnode src/index.js\n```\n\n## Security\n\n- Do not commit tokens, passwords, or private keys.\n- Prefer interactive setup over hardcoded credentials.\n- Stored browser session data is encrypted under `~/.substack-mcp-plus/`.\n- Use obvious placeholders in configs and examples.\n- Re-run authentication if a stored Substack session expires.\n\nSee [SECURITY.md](SECURITY.md) for project security notes.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md","_rev":"1-9fe00699eea50fbbfa895ac4ad02d4c9"}