Substack通讯存档+克劳德桌面MCP
将您的Substack通讯转化为个人知识库，Claude Desktop可以通过自然对话进行搜索、分析和可视化。
这有什么作用
- 摄入 将Substack时事通讯中的每篇文章都存入本地SQLite数据库（全文、元数据、参与度指标）
- 暴露 通过MCP（模型上下文协议）向Claude Desktop提供7个只读工具
- Claude Desktop成为您的前端 --搜索你的档案，分析趋势，比较帖子，生成可视化，所有这些都是用自然语言完成的
需求
- Python 3.12+
- Node.js（用于可选的Mermaid图渲染）
- 克劳德桌面版
- Substack时事通讯（你的——你是作者）
设置
1.创建虚拟环境并安装依赖项
cd newsletter-archive
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt2.配置您的时事通讯
编辑 config.py 并设置您的时事通讯。适用于Substack slug或自定义域：
# Standard Substack URL:
NEWSLETTER_SLUG = "yournewsletter" # → https://yournewsletter.substack.com
# Custom domain:
NEWSLETTER_SLUG = "www.mycustomdomain.com" # → https://www.mycustomdomain.com
# Full URL also works:
NEWSLETTER_SLUG = "https://www.mycustomdomain.com"3.摄取你的文章
.venv/bin/python ingest_runner.py您将看到每篇文章的进展：
Connecting to Substack: yournewsletter... OK
Fetching article archive... found 39 articles
[ 1/39] "Article Title" (2025-07-09)... saved
...
Done: 39 saved, 0 skipped, 0 failed要稍后重新获取所有内容，请执行以下操作： .venv/bin/python ingest_runner.py --full
4.连接到克劳德桌面
打开您的Claude Desktop配置文件：
~/Library/Application Support/Claude/claude_desktop_config.json（在macOS上：Finder→ Go → 转到文件夹→ 粘贴上面的路径）
将此添加到 "mcpServers" 部分（更新路径以匹配您放置此项目的位置）：
{
"mcpServers": {
"my-newsletter": {
"command": "/FULL/PATH/TO/newsletter-archive/.venv/bin/python",
"args": ["/FULL/PATH/TO/newsletter-archive/mcp_server/server.py"],
"env": {
"DB_PATH": "/FULL/PATH/TO/newsletter-archive/newsletter.db"
}
}
}
}重要提示： 使用完整的绝对路径，而不是 ~ 或相对路径。
如果您已经配置了其他MCP服务器，请添加 "my-newsletter" 与它们并排放置（不要替换现有的）。
5.重新启动克劳德桌面
完全退出Claude Desktop（Cmd+Q）并重新打开。通讯工具将自动出现。
你可以问克劳德什么
连接后：
- “我的哪些帖子参与度最高？”
- “向我展示我写的关于\[主题\]的所有内容”
- “我的平均字数随时间有何变化？”
- “哪些免费帖子的表现优于我的付费帖子？”
- “总结我过去10篇文章中的关键主题”
- “我最常谈论的话题是什么？”
可选：添加美人鱼图渲染
让Claude在线生成思维导图、流程图和其他可视化：
将此添加到您的 claude_desktop_config.json 在时事通讯服务器旁边：
"mermaid": {
"command": "npx",
"args": ["-y", "@peng-shawn/mermaid-mcp-server"]
}需要Node.js。然后问克劳德一些事情，比如“为我的时事通讯主题创建一个思维导图。”
MCP工具参考
| 工具 | 说明 |
|---|---|
get_newsletter_info | 通讯名称、作者、文章总数、日期范围、参与摘要 |
search_articles | 按关键字、日期范围、受众类型筛选--返回摘要 |
full_text_search | FTS5搜索所有文章内容--返回片段 |
get_article | 按ID列出一篇文章的全文+元数据 |
get_articles_batch | 一次最多5篇文章的全文 |
get_stats | 总计、平均值、免费与付费细分、按年份分列的文章 |
get_top_articles | 按反应、评论或字数排名 |
项目结构
newsletter-archive/
├── config.py # Your newsletter slug (edit this)
├── ingest_runner.py # CLI: python ingest_runner.py [--full]
├── requirements.txt # 4 dependencies
├── db/
│ ├── schema.py # SQLite tables + FTS5 search index
│ └── operations.py # All database queries
├── ingest/
│ ├── parser.py # HTML → plain text conversion
│ └── fetcher.py # Substack API fetching (two-phase)
├── mcp_server/
│ └── server.py # MCP server with 7 tools
└── docs/
└── spec.md # Full project specification更新您的存档
随时再次运行摄入脚本以获取新文章：
.venv/bin/python ingest_runner.py它只获取数据库中尚未存在的文章（按URL进行重复数据消除）。
故障排除
“未找到时事通讯数据” --你需要奔跑 ingest_runner.py 在使用MCP工具之前。
Claude Desktop未显示工具 --检查你的路径 claude_desktop_config.json 是正确的绝对路径。完全退出并重新打开Claude Desktop。
摄入发现的物品比预期的少 -Substack API可能与分页不一致。提取器使用小页面大小（12）来解决这个问题。如果文章仍然缺失，请尝试 --full.