Substack Vault

English · 中文

Collect Substack newsletters from Zoho Mail, archive them locally, and analyze via MCP Streamable HTTP with cross-author search.

v0.1.0 — Initial release: Zoho sync, Web UI, article library, and MCP tools.

Features

Related MCP server: substack-article-mcp

Requirements

• Python 3.11+

• Zoho Mail account (accounts.zoho.com)

• A Self Client app in Zoho API Console

Quick start

git clone https://github.com/flap4fun/substack-vault.git
cd substack-vault

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

cp .env.example .env               # Windows: copy .env.example .env

Start the server:

substack-vault

Open http://127.0.0.1:8765 in your browser. Use this URL directly — do not serve web/ with Live Server or another static file server.

Connect Zoho Mail

Self Client apps do not support browser OAuth redirects. You must generate a Grant Code manually.

1. Create a Self Client in Zoho API Console

• Type: Self Client

• Redirect URI: http://localhost:8765/oauth/zoho/callback (must match .env)

• Scopes (paste when generating code):

ZohoMail.messages.READ,
ZohoMail.accounts.READ,
ZohoMail.folders.READ,
offline_access

offline_access is required for refresh tokens; without it you must re-authorize when tokens expire.

2. Connect in the Web UI

1. Open 邮箱账号 (Mail accounts) → 连接 Zoho Mail

2. Select your data center (default: Global .com)

3. Enter Client ID, Client Secret, and Grant Code

4. After connecting, use 手动同步 (Sync now) in the top bar

Credentials can also go in .env (see Configuration). UI-saved credentials are stored locally as well.

3. Subscriptions and sync

1. 订阅管理 (Subscriptions) → 扫描发现 (Scan inbox) to discover Substack senders

2. Enable subscriptions you want to sync

3. 手动同步 or wait for the background job (default: every 30 minutes)

Web UI

Display timezone defaults to Asia/Shanghai (UTC+8); the database stores UTC.

Cursor MCP

With substack-vault running, add to Cursor MCP settings:

{
  "mcpServers": {
    "substack-vault": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Tools

Example: ask an agent to compare how different authors cover a topic, or summarize the past week’s posts.

Configuration

.env example (VAULT_ prefix):

# Zoho OAuth
VAULT_ZOHO_CLIENT_ID=
VAULT_ZOHO_CLIENT_SECRET=
VAULT_ZOHO_REDIRECT_URI=http://localhost:8765/oauth/zoho/callback

# Server
VAULT_HOST=127.0.0.1
VAULT_PORT=8765

# Sync (optional)
VAULT_SYNC_INTERVAL_MINUTES=30
VAULT_SYNC_LOOKBACK_DAYS=90
VAULT_SYNC_SUBSCRIBED_ONLY=true

Data directory

Contains vault.db (SQLite), encryption key, and OAuth credentials. Do not commit this directory.

Development

pip install -e ".[dev]"
pytest

Layout:

src/substack_vault/
  api/          FastAPI REST + static Web
  connectors/   Zoho Mail connector
  parsers/      Substack email parser
  sync/         Sync engine
  storage/      SQLAlchemy models & DB
  mcp/          MCP Streamable HTTP
web/            Frontend static assets
tests/          Unit & API tests
openspec/       Specs & change history (OpenSpec)

Roadmap

• Outlook and other mail providers

• RSS body enrichment

• Article tags and advanced filters

• Multi-user / remote deployment

Limitations

• Zoho Mail only (international and regional data centers)

• Single-machine local deployment; no multi-tenant or cloud sync

• Substack HTML parsing depends on email templates; unusual layouts may lose formatting

• MCP endpoint has no authentication — do not expose to the public internet

License

MIT © 2026 flap4fun