SubTrack — 订阅与周期性账单追踪器（MCP 服务器）

**它解决的问题：**几乎每个人都在悄悄流失金钱——那些被遗忘的订阅和周期性账单——一个转为付费的流媒体试用、一张健身房会员卡、一次每年续费却会被遗忘 11 个月的域名续费。SubTrack 让 LLM（Claude 或任何 MCP 客户端）追踪所有这些，告诉你什么即将续费，并显示你归一化为月度数字的总支出——即使你的订阅按周、按月、按季、按年或按自定义周期计费。

功能

另外还有一个 subtrack://categories 资源（可编辑的类别列表）和一个 renewal_digest_prompt 提示模板，用于让助手写一份友好的即将到来事项摘要。

工程上比较有意思的部分是 next_renewal_date()：它用模运算正确推进基于天数的周期（每周/每两周/自定义），并通过添加真实日历月来处理基于日历的周期（每月/每季度/每年）（因此 1 月 31 日开始的订阅会正确落在 2 月 28 日，而不是“31 天后”）。

Related MCP server: subscription-tracker-mcp

为什么这些工具是 async def

这里的每个工具都是 async def，所有 SQLite 访问都通过 aiosqlite 而不是标准库的 sqlite3。值得理解为什么，因为这是一个常见的困惑点：

• FastMCP 默认已经在线程池中运行普通的 def 工具，因此这个服务器的同步版本在轻负载下不会真的卡死。

• 但在 async def 内部使用阻塞驱动（sqlite3）比保持同步更糟——FastMCP 不会对 async def 工具做线程卸载（它们直接运行在事件循环上），所以其中的阻塞调用会拖慢所有其他并发请求。

• 所以：要么让工具保持 def 并让框架做线程卸载，要么使用 async def 并且一路用真正异步的驱动。这个服务器选择了后者，这对于可能同时收到多个客户端并发工具调用的远程服务器来说是更具可扩展性的模式——它不会为每个进行中的数据库调用消耗一个工作线程，而且如果你以后添加其他可等待的 I/O（HTTP 调用等），它也能干净地组合。

• 唯一的例外：微小的 categories.json 读取保持普通同步。它每次调用只读取几百字节——把它变成“async”意味着要添加 aiofiles，却没有任何实际的并发收益。

项目结构

subtrack-mcp/
├── server.py          # the whole server — module-level `mcp` object
├── pyproject.toml     # project metadata + deps (managed by uv)
├── uv.lock            # locked, reproducible dependency versions
├── .python-version    # pins the Python version uv uses
├── .gitignore
└── README.md

categories.json 和 subscriptions.db 不会被提交——server.py 会在首次运行时自动创建它们（参见 init_categories() / init_db()）。如果你希望自己固定的类别列表在重新部署后仍然保留，请将 categories.json 从 .gitignore 中移除并提交你编辑过的版本。

本地运行（uv）

无需手动创建 venv——uv run 会在你第一次使用时自动从 uv.lock 创建并同步 .venv。

server.py 中的 __main__ 块默认通过 HTTP 在 0.0.0.0:8000 上运行服务器（可用 PORT 环境变量覆盖）——这与 FastMCP Cloud 在生产环境中使用的传输方式相同，因此本地测试与你实际部署的环境一致：

uv run server.py
# Starting MCP server 'SubTrack' with transport 'http' on http://0.0.0.0:8000/mcp

注意：这个块只在你直接执行文件时运行。FastMCP Cloud 会完全忽略它——它导入 mcp 对象并自行提供服务，所以这里的内容不会影响已部署的服务器。

用一个快速客户端脚本测试（uv run python client_test.py）：

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://127.0.0.1:8000/mcp") as client:
        result = await client.call_tool("add_subscription", {
            "name": "Netflix", "amount": 15.99, "billing_cycle": "monthly",
            "start_date": "2026-08-05", "category": "Streaming", "subcategory": "Video"
        })
        print(result.data)

asyncio.run(main())

如果你想用期望 stdio 的 MCP 客户端测试（例如在本地使用中把它接入 Claude Desktop），可以通过 FastMCP CLI 运行，它会覆盖传输方式，无论 __main__ 里是什么：

uv run fastmcp run server.py:mcp --transport stdio

添加或更新依赖

不要手工编辑 pyproject.toml 的依赖列表——让 uv 来管理，这样 uv.lock 才能保持同步：

uv add some-package             # add a new dependency
uv add some-package --upgrade   # bump one dependency
uv lock --upgrade               # re-resolve everything to latest compatible versions

部署到 FastMCP Cloud

1. 把这个文件夹推送到 GitHub 仓库——提交 pyproject.toml 和 uv.lock（不要提交 .venv/，它已被 gitignore）。

2. 用 GitHub 登录 fastmcp.cloud，并从该仓库创建一个新项目。

3. 将入口点设置为：

   server.py:mcp

4. 部署。FastMCP Cloud 会自动从 pyproject.toml 检测依赖（它也理解纯 requirements.txt，但这里你不需要）。你会得到一个类似 https://<project>.fastmcp.app/mcp 的 URL，任何 MCP 客户端——包括通过自定义连接器的 Claude——都可以调用。

关于存储的说明

这个服务器为了简单起见使用本地磁盘上的 SQLite，这非常适合学习和单实例部署。在大多数托管平台上，它不能保证在重新部署后仍然存在（新的部署通常意味着新的文件系统）。当你对工具逻辑满意后，自然的下一步——也是进一步学习远程 MCP 服务器的好练习——是把 sqlite3 换成托管数据库（Turso/libSQL、通过 asyncpg 的 Postgres、Supabase 等），使用环境变量来设置连接字符串，在 FastMCP Cloud 仪表板中配置（os.getenv("DATABASE_URL")）。

扩展思路

• 添加一个 mcp.tool()，使用 renewal_digest_prompt 的输出发送摘要邮件或推送。

• 添加一个 price_history 表和一个记录价格随时间上涨的工具。

• 当你准备好让服务器变为私有而不是开放时，添加身份验证（FastMCP 支持 bearer-token 认证）。