Substack Gateway OSS

A stateless Python gateway for Substack that exposes a REST API and an MCP server on top of the same service layer.

Designed to make Substack data and actions accessible from scripts, applications, and AI tooling — without duplicating integration logic across different interfaces.

What You Can Do

• Read public Substack profiles, posts, notes, and comments
• Access authenticated me endpoints with a base64-encoded credential token
• Create and delete notes through the REST API
• Use the same gateway as an MCP server for AI tools and agent workflows
• Extend the app with custom routes, MCP tools, auth providers, and lifespan hooks

Interfaces

• REST API at /api/v1/*
• MCP server at /mcp

Both share the same service layer and HTTP clients. The thin substack_gateway shell package assembles the application (REST + MCP composition), while gateway_oss provides the OSS module surface as a facade.

Quickstart

Requirements:

• Python 3.10+
• uv

Install dependencies:

uv sync --dev

Run the application locally:

uv run python -m substack_gateway.main

Check the root metadata endpoint:

curl http://127.0.0.1:5001/

Check the liveness probe:

curl http://127.0.0.1:5001/api/v1/health/live

Fetch a public profile:

curl http://127.0.0.1:5001/api/v1/profiles/<slug>

REST Example

Public profile lookup:

curl http://127.0.0.1:5001/api/v1/profiles/<slug>

Authenticated request:

curl \
  -H "x-gateway-token: <base64-encoded-json>" \
  http://127.0.0.1:5001/api/v1/me

The REST API is mounted under /api/v1 and includes endpoints for health, profiles, posts, notes, comments, and authenticated me operations.

Authentication

Gateway access and Substack access are separate concerns.

For this OSS repository, Substack credentials are passed as a base64-encoded JSON object. REST requests send that value as the x-gateway-token header.

Credential shape:

{
  "publication_url": "https://example.substack.com",
  "substack_sid": "s%3A...",
  "connect_sid": "s%3A..."
}

Encode it with:

echo '{"publication_url":"https://example.substack.com","substack_sid":"s%3A...","connect_sid":"s%3A..."}' | base64

Treat substack_sid and connect_sid as bearer credentials. Do not commit real values to the repository.

MCP

The MCP server is mounted at /mcp and served over streamable HTTP.

Public OSS MCP tools include:

• get_note
• get_post
• get_post_comments
• get_profile
• get_profile_posts
• get_profile_notes

Project Layout

Core application code lives in src/gateway_oss/.

• api/v1/: FastAPI route handlers
• mcp/: FastMCP tool surface and transport integration
• services/: shared business logic
• client/: Substack HTTP client wrappers
• models/: schemas and pagination models
• converters/: Markdown conversion
• extensions/: runtime extension hooks

Configuration

Application settings are environment-driven via the SUBSTACK_GATEWAY_ prefix.

Common examples include:

• SUBSTACK_GATEWAY_LOG_LEVEL
• SUBSTACK_GATEWAY_SUBSTACK_BASE_URL
• SUBSTACK_GATEWAY_SUBSTACK_TIMEOUT_SEC

Validation

uv run ruff check .
uv run ruff format --check .
uv run ty check .
uv build
uv run pytest tests/
uv run behave features/

Documentation

The repository includes MkDocs and Read the Docs configuration:

• Docs home
• Introduction
• Installation guide
• Authentication
• API reference
• MCP documentation
• Development guide
• Contributing guide

Read the Docs can build the site directly from .readthedocs.yaml and mkdocs.yml.

Author

Built by Jakub Slys — Backend Engineer building distributed systems for telecoms, running a self-hosted Kubernetes homelab, and building AI automation pipelines with n8n, MCP, and Claude.

This gateway is the backend I use to automate my own Substack at iam.slys.dev, where I write about system design, machine learning fundamentals, and the AI tools I actually build and run in production.

If you want to understand how this gateway works under the hood — the architecture decisions, what I got wrong the first time, and how it fits into a full content automation stack — that's what the newsletter is for.

→ iam.slys.dev