outbank MCP

外发银行MCP CSV工作区


安装

pip install mcp-outbank
# or run directly without installing:
uvx mcp-outbank

本地第一MCP查询服务，从文件夹读取Outbank CSV导出， 规范内存中的事务，并公开搜索和聚合工具 LLMs。支持Docker容器化设置和直接Python执行。

目的和责任

此项目仅用于使用导出向LLM提供您的财务数据 来自流行的Outbank工具。您对数据的方式负责 处理、导出、存储和共享。比起大型科技公司，更喜欢本地模式 尽可能使用LLMs。如果您确实使用外部模型，请使用MCP进行查询 您的本地数据比重复上传原始CSV导出更安全。

⚠️ 🔒 🚫 仅本地警告 该项目仅供当地使用。 公开披露MCP服务不在范围内，完全由您自行承担风险。 看 docs/security.md 对于推荐的仅本地设置和强制HTTP身份验证要求。

🚨 安全：假冒警告 切勿与声称是此项目的贡献者或维护者的任何人共享凭据或CSV文件。 该项目的贡献者和维护者将 永不 请您： - 您的凭据（密码、API密钥、令牌） - CSV导出文件 - 访问您的财务数据 如果有人要求这些，他们就是在冒充我们。报告他们，不要遵守。

为什么不直接使用Outbank？

Outbank非常擅长向您展示交易。它有过滤器、类别和搜索。 但有一类问题它无法回答——这些问题需要 推理不仅仅是过滤。

“我搬家后，我的杂货支出增加了吗？”不是一个过滤查询。它要求 比较两个日期范围，在每个范围内求和一个类别，并得出结论。 “查找每个定期订阅并计算年度成本”需要检测 几个月的模式。“带我走过我的薪水去了哪里”需要转身 40行项目组成一个可读的叙述。

连接到此MCP服务器的LLM可以完成所有这些。Outbank为您展示 交易。LLM 解释 他们。

Outbank不能做的另一件事是与您的其他工具交谈。因为这运行 作为MCP服务器，Claude可以在同一对话中查询您的银行数据 阅读日历、查看电子邮件或更新任务管理器。“我有一份工作 上周的旅行——一次性从两台MCP服务器上提取费用。没有 银行应用程序将永远做到这一点。

可能出现的提示示例：

• “给我一个简单的语言总结，说明我一月份的钱去了哪里。”
• “与三个月前相比，我在外出就餐上花的钱多了吗？”
• “查找过去六个月内出现的任何新的经常性费用。”
• “我今年的哪些交易可以减税？”
• “我3月10日至13日在柏林上班，给我写一份费用报告。”
• “这个月我被指控两次了吗？”

这里是什么

• 用于CSV文件夹摄取和查询工具的Python MCP服务（FastMCP 3.0）
• 五种工具： search_transactions, aggregate_transactions, describe_fields, reload_transactions, health_check
• stdio和HTTP传输模式的自动化测试套件

- 单元测试、错误处理和用户工作流测试 - 使用Gherkin特征文件进行BDD工作流测试（pytest-BDD）

• 关于Outbank CSV导出格式和规范化的说明
• 外发银行CSV导出示例(outbank_export_example.csv)

快速开始

选择Docker或直接执行Python：

选项1:Docker（推荐用于隔离环境）

1. 确保已安装Docker和Docker Compose

1. 复制环境模板：

   cp .env.example .env

1. 在中配置CSV目录 .env:

   OUTBANK_CSV_DIR=./outbank_exports

1. 构建并启动服务：

   docker-compose up --build

该服务将通过配置端口上的stdio（默认）或HTTP提供。

要在分离模式下运行：

   docker-compose up -d

要查看日志，请执行以下操作：

   docker-compose logs -f finance-mcp

停止：

   docker-compose down

选项2：直接执行Python

1. 安装 uv: https://github.com/astral-sh/uv
2. 复制环境模板并配置：

   cp .env.example .env

1. 安装依赖项：

   uv sync

1. 使用stdio传输运行MCP服务（默认）：

   uv run python app.py

或者使用HTTP传输（仅JSON响应，没有SSE流， 需要身份验证):

   MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=6668 \
     MCP_HTTP_AUTH_TOKEN=your-secret-token \
     uv run python app.py

备注: MCP_HTTP_AUTH_TOKEN 使用HTTP传输时需要（最少16个字符，建议32+）。如果令牌丢失或太短，服务将无法启动。使用以下方法生成安全令牌：

   python -c "import secrets; print(secrets.token_urlsafe(32))"

CSV格式

外发银行出口使用分号分隔的CSV，采用德国日期格式 小数逗号。预期标题示例：

#;Account;Date;Value Date;Amount;Currency;Name;Number;Bank;Reason;Category;Subcategory;Category-Path;Tags;Note;Posting Text

配置

交易排除筛选器

您可以通过在您的 .env 文件。排除的交易在CSV摄取过程中会被过滤，永远不会出现在搜索结果中。

环境变量：

• EXCLUDED_CATEGORIES：逗号分隔的要排除的类别列表（例如。， Transfer,Internal,Reconciliation)
• EXCLUDED_TAGS：逗号分隔的要排除的标签列表（例如。， transfer,internal)

特征：

• 多字段匹配：类别排除检查 category, subcategory，以及 category_path 领域。例如， Transfer 即使类别是“财务和保险”，也会将交易与子类别“转账”相匹配
• 不区分大小写的匹配：无论情况如何，排除过滤器都匹配（例如。， transfer 火柴 Transfer, TRANSFER等等）
• 部分匹配：如果排除值出现在类别/子类别/路径或标签中的任何位置，则它们匹配（例如。， transfer 火柴 internal-transfer 或 Finances & Insurances / Transfer)
• 在加载时应用：排除的交易在CSV摄取过程中过滤，而不是在查询时过滤
• 空白处理：值周围的多余空格会自动修剪

示例 .env 配置：

# Exclude transfer transactions by category
EXCLUDED_CATEGORIES=Transfer,Internal

# Exclude transactions with specific tags
EXCLUDED_TAGS=transfer,internal

示例用例：

• 不包括您自己账户之间的内部转账
• 过滤掉对账交易
• 删除您不想分析的特定交易类型
• 清理重复或噪音交易

它是如何工作的：

1. 在您的计算机中配置排除筛选器 .env 文件
2. 加载CSV文件时（启动时或通过 reload_transactions)，筛选出符合排除条件的交易
3. 排除的事务永远不会进入内存中的事务存储
4. 搜索结果将不包括排除的交易

重要提示：

• 加载或重新加载事务时应用排除过滤器。更换排除过滤器后，使用 reload_transactions 应用新过滤器的工具。
• 如果交易匹配 任何 排除类别 或 任何被排除的标签，都将被排除
• 排除列表中的空值或仅空白值将被忽略
• 要禁用排除，请保持环境变量未设置或将其设置为空字符串

验证排除： 配置排除筛选器并重新加载事务后，您可以验证它们是否正常工作：

1. 使用 describe_fields 查看加载的记录总数
2. 使用 search_transactions 使用通常与排除的交易匹配的查询
3. 排除的交易不应出现在结果中

文档

• MCP服务详情： docs/mcp.md
• 安全指南： docs/security.md
• 外发银行CSV导入步骤： docs/outbank-import.md

测试

自动测试可用于验证MCP服务器在stdio和HTTP传输模式下的功能。

快速开始

1. 安装测试依赖项：

   uv sync --group dev

1. 运行所有测试：

   uv run pytest tests/

1. 对于HTTP传输测试，请先通过身份验证启动服务器：

   MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=6668 \
     MCP_HTTP_AUTH_TOKEN=test-token-12345678 \
     uv run python app.py

测试类型

测试套件包括：

• 单元测试：基本功能测试(test_simple_queries.py, test_advanced_queries.py)
• 错误处理测试：边缘情况和错误条件(test_error_handling.py)
• 用户工作流测试：端到端工作流模拟(test_user_workflow.py)
• BDD工作流测试：使用Gherkin特征文件的行为驱动开发测试(tests/features/, tests/step_defs/)

BDD工作流测试

该项目包括 行为驱动开发（BDD） 测试使用 pytest-bdd 以及Gherkin特征文件。这些测试提供了人类可读的场景，作为实时文档。

可用的BDD工作流：

• 月度费用分析
• 对账
• 渐进式搜索优化
• 输入处理无效
• 数据状态管理
• HTTP 认证

运行BDD测试：

# Run all BDD tests
uv run pytest tests/step_defs/ -v

# Run specific workflow
uv run pytest tests/step_defs/test_monthly_expense.py -v

示例特征文件：

Feature: Monthly Expense Analysis
  Scenario: Analyze expenses for January 2024
    Given the MCP server is running
    And CSV data is loaded
    When I search for transactions from "2024-01-01" to "2024-01-31"
    Then I should see expense summary with transaction count

看 tests/README.md 详细的测试文件，包括：

• 测试结构和组织
• 运行特定的测试套件（stdio与HTTP）
• BDD工作流测试细节和示例
• 经过身份验证的HTTP测试的环境设置
• 测试覆盖率详细信息
• OpenAI MCP合规性验证(tests/MCP_COMPLIANCE.md)

发展

预提交挂钩

此项目使用 预承诺 在每次提交之前运行代码质量检查。

设置：

uv sync --group dev
uv run pre-commit install

它检查什么：

• 代码格式化（ruff格式）
• 绒毛（褶皱检查）
• 尾随空格、合并冲突、大文件
• YAML/JSON语法验证

手动运行：

uv run pre-commit run --all-files

Opsx/OpenSpec命令

Opsx命令和技能在 .cursor/commands/ 和 .cursor/skills/ （唯一的真相来源）。对于Claude IDE，从那里复制或符号链接到 .claude/commands/opsx/ 和 .claude/skills/ 如果需要（例如。 opsx-apply.md → .claude/commands/opsx/apply.md).

支持这个项目

如果你觉得这很有用，可以考虑给我买杯咖啡： https://buymeacoffee.com/caseyberlin

此处使用的开源项目

• FastMCP：https://github.com/jlowin/fastmcp
• pythonhttps://www.python.org/
• 紫外线：https://github.com/astral-sh/uv

外箱

• 产品：https://outbankapp.com/
• 外库团队：https://outbankapp.com/ueber-outbank/
• 联盟链接（免费月）：https://outbankapp.com/affiliate-gratismonat/?id=outbank_mcp

- 披露：这是一个联盟链接。