Quicken Simplifi MCP

加快简化MCP服务器

用于快速简化事务的单用户MCP服务器（Node.js+TypeScript）。

它提供MCP工具：

• list_transactions
• search_transactions
• get_transaction
• update_transaction
• categorize_transaction
• list_uncategorized_transactions
• search_merchants
• list_categories / search_categories
• list_tags / search_tags
• suggest_categories_for_merchant

它包括：

• 本地事务缓存（SQLite）
• Simplifi自动全同步+增量同步
• OAuth 2.0（授权码+PKCE，加上刷新令牌）来保护 /mcp

运作原理

1） 简化上游身份验证

此服务器通过以下方式向Simplifi进行身份验证：

• SIMPLIFI_EMAIL
• SIMPLIFI_PASSWORD

默认情况下，它使用在HAR流量中观察到的Simplifi web客户端值：

• SIMPLIFI_CLIENT_ID=acme_web
• SIMPLIFI_CLIENT_SECRET=BCDCxXwdWYcj@bK6
• SIMPLIFI_REDIRECT_URI=https://simplifi.quicken.com/login

运行时行为：

1. 使用...登录 /oauth/authorize + /oauth/token 以获得代币。
2. 在本地SQLite中持久访问/刷新令牌。
3. 访问令牌过期时自动使用刷新令牌。

2） MCP下游认证

您的MCP客户端通过OAuth 2.0对此服务器进行身份验证：

• GET /oauth/authorize
• POST /oauth/token
• 承载访问令牌打开 Authorization: Bearer ... 为了 /mcp

这使得Simplifi凭据/令牌仅在服务器端使用。

3） 本地缓存和同步

• 首次运行时，它会与Simplifi事务进行完全同步。
• 后台增量同步每 SIMPLIFI_SYNC_INTERVAL_MS.
• 工具调用还可以增强新鲜度(SIMPLIFI_MAX_STALE_MS)在查询缓存之前。

项目布局

• src/index.ts：应用程序引导
• src/http/server.ts：HTTP服务器、OAuth端点、MCP传输
• src/mcp/server.ts：MCP工具定义
• src/services/transaction-tool-service.ts：工具行为
• src/simplifi/*：简化auth+neneneba API客户端
• src/sync/sync-service.ts：同步编排
• src/db/database.ts：SQLite模式+存储库方法

需求

• Node.js 20+
• 纱线1.x

设置

1. 安装依赖项

yarn install

1. 创建env文件

cp .env.example .env

1. 填写所需变量 .env

最低要求：

• OAUTH_JWT_SECRET
• OAUTH_LOGIN_USERNAME
• OAUTH_LOGIN_PASSWORD
• SIMPLIFI_EMAIL
• SIMPLIFI_PASSWORD
• SIMPLIFI_DATASET_ID
• SIMPLIFI_THREAT_METRIX_SESSION_ID （推荐；当前Simplifi授权流程要求）

可选但推荐：

• OAUTH_ALLOWED_REDIRECT_URIS （逗号分隔的列表）
• PUBLIC_BASE_URL
• CACHE_DB_PATH

1. 在开发中运行

yarn dev

1. 构建和运行生产

yarn build
yarn start

MCP端点

• MCP网址： https:///mcp
• OAuth授权URL： https:///oauth/authorize
• OAuth令牌URL: https:///oauth/token

工具合同

list_transactions

输入（全部可选）：

• limit （1-200，默认值50）
• cursor
• accountId
• dateFrom (YYYY-MM-DD)
• dateTo (YYYY-MM-DD)
• minAmount
• maxAmount
• includeDeleted
• refresh

search_transactions

输入：

• query （必填）
• 与相同的可选过滤器 list_transactions

get_transaction

输入：

• transactionId （必填）
• refreshOnMiss （可选，默认为true）

update_transaction

输入：

• transactionId （必填）
• patch （必填对象）

update_transaction 合并 patch 在缓存的事务中，验证所需的Simplifi追加销售字段，发送 PUT /transactions/{transactionId}，然后重新同步。

categorize_transaction

输入：

• transactionId （必填）
• categoryId （必填）

集合 coa.type=CATEGORY 和 coa.id= 通过 update_transaction.

list_uncategorized_transactions

输入：与 list_transactions

返回未分类的交易（通常 coa.type=UNCATEGORIZED 或 coa.id=0).

search_merchants

输入：

• query （必填）
• limit （可选，1-200）
• includeDeleted （可选）

返回从缓存交易中得出的商家名称建议（分组和计数）。

list_categories

输入：

• refresh （可选）
• limit （可选，1-5000）

search_categories

输入：

• query （必填）
• refresh （可选）
• limit （可选，1-5000）

list_tags

输入：

• refresh （可选）
• limit （可选，1-5000）

search_tags

输入：

• query （必填）
• refresh （可选）
• limit （可选，1-5000）

suggest_categories_for_merchant

输入：

• merchant （必填）
• limit （可选，1-20）
• matchMode （可选： exact 或 contains)
• refreshCategories （可选）

返回缓存交易中该商家历史上使用的最常见类别（在可用时与类别名称连接）。

生产部署

选项A:systemd（VM/裸机）

1. 构建应用程序：

yarn install --frozen-lockfile
yarn build

1. 使用TLS在反向代理（Nginx/Caddy）后面运行。

1. 商店 .env 外部仓库和保护文件权限。

1. 使用一个 systemd 运行的服务：

node /path/to/app/dist/index.js

选项B:Docker

构建图像：

docker build -t simplifi-mcp:latest .

运行容器：

docker run -d \
  --name simplifi-mcp \
  --restart unless-stopped \
  -p 8787:8787 \
  --env-file .env \
  -v simplifi_mcp_data:/app/data \
  simplifi-mcp:latest

安全说明

• 对待 .env 敏感。
• 使用强力 OAUTH_JWT_SECRET （32+随机字节）。
• 集 OAUTH_ALLOWED_REDIRECT_URIS 在生产中。
• 将服务器置于HTTPS之后。
• 限制网络访问（防火墙、VPN或零信任访问策略）。

操作说明

• 健康终点： GET /healthz
• OAuth元数据：

- GET /.well-known/oauth-authorization-server - GET /.well-known/openid-configuration

• Cache位于SQLite中 CACHE_DB_PATH.

故障排除

• 401 invalid_token 上 /mcp:

- 令牌已过期/无效，请重新运行OAuth流。

• 简化同步错误：

- 验证 SIMPLIFI_EMAIL, SIMPLIFI_PASSWORD，以及 SIMPLIFI_DATASET_ID.

• 首次启动时清空缓存：

- 初始完全同步在后台运行；请稍候，然后重试工具调用。