https://github.com/jakub-k-slys/substack-gateway-oss
Stateless Substack Gateway exposing a REST API and MCP for reading profiles, posts, notes, and comments, plus authenticated personal and note-publishing workflows.
https://github.com/jakub-k-slys/substack-gateway-oss
ai-tools automation fastapi fastmcp gateway integration mcp model-context-protocol python rest rest-api substack vercel
Last synced: about 1 month ago
JSON representation
Stateless Substack Gateway exposing a REST API and MCP for reading profiles, posts, notes, and comments, plus authenticated personal and note-publishing workflows.
- Host: GitHub
- URL: https://github.com/jakub-k-slys/substack-gateway-oss
- Owner: jakub-k-slys
- License: mit
- Created: 2026-03-18T20:01:34.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T11:20:33.000Z (about 1 month ago)
- Last Synced: 2026-04-25T13:24:41.740Z (about 1 month ago)
- Topics: ai-tools, automation, fastapi, fastmcp, gateway, integration, mcp, model-context-protocol, python, rest, rest-api, substack, vercel
- Language: Python
- Homepage: https://substack-gateway-oss.readthedocs.io/
- Size: 1.92 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Substack Gateway OSS
[](https://github.com/jakub-k-slys/substack-gateway-oss/actions/workflows/ci.yaml)
[](https://github.com/jakub-k-slys/substack-gateway-oss/actions/workflows/e2e.yaml)
[](https://substack-gateway.vercel.app)
A stateless Python gateway for [Substack](https://substack.com) that exposes a
REST API and an MCP server on top of the same service layer.
It is designed to make Substack data and actions easier to consume 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](https://docs.astral.sh/uv/)
Install dependencies:
```bash
uv sync --dev
```
Run the application locally:
```bash
uv run python -m gateway_oss.main
```
Check the root metadata endpoint:
```bash
curl http://127.0.0.1:5001/
```
Check the liveness probe:
```bash
curl http://127.0.0.1:5001/api/v1/health/live
```
Fetch a public profile:
```bash
curl http://127.0.0.1:5001/api/v1/profiles/
```
## REST Example
Public profile lookup:
```bash
curl http://127.0.0.1:5001/api/v1/profiles/
```
Authenticated request:
```bash
curl \
-H "x-gateway-token: " \
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:
```json
{
"publication_url": "https://example.substack.com",
"substack_sid": "s%3A...",
"connect_sid": "s%3A..."
}
```
Encode it with:
```bash
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`
## Documentation
The repository includes MkDocs and Read the Docs configuration:
- [Docs home](docs/index.md)
- [Introduction](docs/introduction.md)
- [Installation guide](docs/installation.md)
- [Authentication](docs/authentication.md)
- [API reference](docs/api-reference.md)
- [MCP documentation](docs/mcp.md)
- [Development guide](docs/development.md)
- [Contributing guide](CONTRIBUTING.md)
Read the Docs can build the site directly from `.readthedocs.yaml` and `mkdocs.yml`.
## Validation
```bash
uv run ruff check .
uv run ruff format --check .
uv run ty check .
uv build
uv run pytest tests/
uv run behave features/
```