Plaid Transactions MCP Server

Plaid交易MCP服务器

模型上下文协议（MCP）服务器，提供与Plaid的事务API交互的工具。此服务器使Claude能够安全地同步、搜索和分析您的金融交易。

特性

🛠️ 四大强大工具

1. plaid_list_accounts -列出所有链接的Plaid帐户

- 显示存储在钥匙串中的所有帐户 - 显示友好名称（例如“美国运通”、“花旗银行”） - 使用此功能查看可以查询哪些帐户

1. plaid_sync_transactions -使用自动分页同步所有交易

- 检索添加、修改和删除的交易 - 支持按帐户和日期范围过滤 - 自动处理基于光标的分页 - 适用于多个帐户-按名称指定 - 返回Markdown或JSON格式的数据

1. plaid_get_transaction_categories -获取Plaid的交易类别分类

- 显示所有可用类别及其层次结构 - 有助于理解交易分类 - 不要求进行验证

1. plaid_search_transactions -智能搜索和过滤交易

- 按商户名称、类别、金额范围或日期筛选 - 支持商家和类别搜索的部分匹配 - 适用于多个帐户-按名称指定 - 在一个操作中结合同步和过滤

🔐 安全功能

• 将凭据存储在 macOS钥匙扣 （从不在文件中）
• 代码或环境文件中没有凭据
• 遵循安全凭据管理最佳实践

⚡ 智能功能

• 自动分页 -无需手动分页即可获取所有数据
• 响应截断 -在有用的指导下优雅地处理大型数据集
• 清除错误消息 -可操作的错误消息指导您找到解决方案
• 双输出格式 -人类可读的Markdown或机器可读的JSON

______________________________________________________________________

安装

1.安装依赖项

cd ~/plaid-transactions-mcp
pip install -r requirements.txt

2.在Keychain中设置Plaid凭据

您需要在macOS Keychain中存储三个值：

# Store your Plaid Client ID
security add-generic-password -s "PLAID_CLIENT_ID" -a "plaid" -w "your_client_id_here"

# Store your Plaid Secret
security add-generic-password -s "PLAID_SECRET" -a "plaid" -w "your_secret_here"

# Store your Plaid Access Token (obtained after linking an account)
security add-generic-password -s "PLAID_ACCESS_TOKEN" -a "plaid" -w "access-sandbox-xxx"

从哪里获取这些值：

• 客户端ID和密码：从 格子仪表板
• 访问令牌：用户完成Plaid链接流后获得（见下文）

3.获取访问令牌

要获得交易，您首先需要一个访问令牌，让用户链接他们的银行账户：

1. 使用创建链接令牌 /link/token/create 和 transactions 在产品阵列中
2. 用户在您的应用程序中完成Plaid链接流
3. 使用以下方式将公共令牌交换为访问令牌 /item/public_token/exchange
4. 将访问令牌存储在Keychain中

为了进行测试，请使用 格子沙箱 资格证书。

4.配置克劳德桌面

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "plaid-transactions": {
      "command": "python",
      "args": ["/Users/sfinnerty/plaid-transactions-mcp/plaid_mcp.py"]
    }
  }
}

5.重新启动克劳德桌面

更新配置后，重新启动Claude Desktop以加载MCP服务器。

______________________________________________________________________

使用示例

列出您的帐户

What Plaid accounts do I have?

克劳德将使用 plaid_list_accounts 显示您的所有链接帐户。

同步所有最近的交易

Show me my recent American Express transactions

克劳德将使用 plaid_sync_transactions 使用美国运通账户。

Show me all transactions from my Citibank account

Claude将自动选择花旗银行账户。

搜索特定商家

Find all my Starbucks purchases from last month

克劳德将使用 plaid_search_transactions 带有商家和日期过滤器。

按金额筛选

Show me all transactions over $100 in December 2024

克劳德将使用金额和日期过滤器进行搜索。

查看交易类别

What categories does Plaid use for transactions?

克劳德将使用 plaid_get_transaction_categories.

按类别筛选

List all my travel expenses from Q4 2024

Claude将搜索与旅行相关类别的交易。

______________________________________________________________________

工具详细信息

plaid_sync_交易

目的：检索自上次光标位置以来的所有交易更新。

参数:

• access_token （必填）：您的Plaid访问令牌
• cursor （可选）：来自上次同步的分页光标
• count （可选）：每页交易数（默认值：100，最大值：500）
• account_ids （可选）：筛选到特定帐户
• date_start （可选）：开始日期（YYYY-MM-DD）
• date_end （可选）：结束日期（YYYY-MM-DD）
• response_format （可选）：“markdown”或“json”（默认：markdown）

退货:

• 新增交易（自上次同步以来新增）
• 已修改的交易记录（自上次同步后更新）
• 已删除交易（自上次同步以来已删除）
• 增量同步的下一个光标

plaid_get_transaction_类别

目的：获取Plaid交易类别的完整分类。

参数：无

退货:

• 所有类别的分层列表
• 类别ID和完整路径（例如，“食品和饮料>餐厅>咖啡店”）

plaid_search_transactions

目的：按多个条件搜索和筛选交易。

参数:

• access_token （必填）：您的Plaid访问令牌
• merchant_name （可选）：按商家筛选（部分匹配）
• category （可选）：按类别筛选（部分匹配）
• min_amount （可选）：最低交易金额
• max_amount （可选）：最大交易金额
• date_start （可选）：开始日期（YYYY-MM-DD）
• date_end （可选）：结束日期（YYYY-MM-DD）
• account_ids （可选）：筛选到特定帐户
• response_format （可选）：“markdown”或“json”（默认：markdown）

退货:

• 匹配交易的筛选列表
• 应用的筛选器和匹配计数摘要

______________________________________________________________________

环境配置

在沙盒和生产之间切换

默认情况下，服务器使用Plaid的生产API。要使用沙盒进行测试，请执行以下操作：

编辑 plaid_mcp.py 第26行：

# For sandbox testing
PLAID_API_URL = "https://sandbox.plaid.com"

# For production
PLAID_API_URL = "https://production.plaid.com"

沙盒测试用户

Plaid在沙盒模式下为测试用户提供：

• user_good -具有事务的标准测试用户
• user_transactions_dynamic -刷新时生成新交易

______________________________________________________________________

错误处理

服务器提供清晰、可操作的错误消息：

• 无效访问令牌：“令牌可能已过期。请通过Plaid link重新链接帐户。”
• 请求频率超限：“Plaid限制为每分钟100个请求。等待60秒。”
• 需要项目登录：“用户需要通过Plaid Link重新进行身份验证。”
• 缺少钥匙链凭据：提供存储凭据的精确命令

______________________________________________________________________

故障排除

“从钥匙链检索失败”

确保您已将所有三个值存储在Keychain中：

# Verify credentials are stored
security find-generic-password -s "PLAID_CLIENT_ID" -w
security find-generic-password -s "PLAID_SECRET" -w

“访问令牌无效”

您的访问令牌可能已过期。您需要：

1. 让用户通过Plaid Link重新进行身份验证
2. 将新的公共令牌替换为新的访问令牌
3. 用新令牌更新密钥链

“超出费率限制”

Plaid将生产中的请求限制在每分钟100个。等待60秒后重试。

服务器未出现在Claude Desktop中

1. 检查配置文件路径是否正确
2. 验证配置中的Python路径
3. 完全重新启动克劳德桌面
4. 检查Claude Desktop日志是否有错误

______________________________________________________________________

发展

测试服务器

# Check syntax
python -m py_compile plaid_mcp.py

# Run the server (will hang waiting for stdio - this is normal)
python plaid_mcp.py

编码结构

• 工具函数：密钥链访问、API请求、错误处理、格式化
• Pydantic模型：所有工具的输入验证
• 工具实施：具有全面文档字符串的三个主要工具
• 错误处理：始终显示清晰、可操作的错误消息

______________________________________________________________________

安全最佳实践

✅ 做:

• 将凭据存储在macOS钥匙串中
• 使用特定于环境的API URL（沙箱与生产版）
• 使用Pydantic模型验证所有输入
• 用清晰的信息优雅地处理错误

❌ 不要:

• 将凭据存储在 .env 文件
• 将凭据提交到git
• 代码中的硬代码API密钥
• 在错误消息中暴露敏感数据

______________________________________________________________________

资源

• 虚假交易API单据
• 格子仪表板
• MCP文件
• FastMCP Python SDK

______________________________________________________________________

许可证

此MCP服务器按原样提供，用于Plaid的交易API。确保遵守Plaid的服务条款和API使用政策。