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.

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:

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

substack-gateway-oss