jakub-k-slys/substack-gateway-oss

uv sync --dev && uv run python -m substack_gateway.main

Usage

• •Run locally and hit the REST API at /api/v1/* (profiles, posts, notes, comments, health, authenticated me).
• •Pass Substack credentials as a base64-encoded JSON object ({publication_url, substack_sid, connect_sid}) in the x-gateway-token header.
• •Connect any MCP client to the /mcp endpoint for tools like get_note, get_post, get_post_comments, get_profile, get_profile_posts, get_profile_notes.
• •Extend with custom routes, MCP tools, auth providers and lifespan hooks via the extensions layer.

Key features

• ✓One service layer behind both REST (FastAPI) and MCP (FastMCP) surfaces.
• ✓Read public Substack data and create/delete notes through authenticated endpoints.
• ✓Environment-driven config with SUBSTACK_GATEWAY_ prefix.
• ✓MkDocs/Read the Docs documentation, ruff + ty + pytest + behave validation.

Best for

Automating your own Substack (content extraction, notes, analytics) from scripts or AI agents via a self-hosted gateway.

Caveats

• ⚠Auth relies on raw session cookies (substack_sid/connect_sid) treated as bearer credentials — handle and store them carefully.
• ⚠Auth is a separate concern from gateway access; needs Python 3.10+ and uv.
• ⚠Also deployed on Vercel (substack-gateway.vercel.app).