财务数据分析MCP服务器及Web应用
强大的模型上下文协议（MCP）服务器 具有web界面 使用OpenRouter、OpenAI或任何与OpenAI兼容的API提供商的AI驱动分类来分析金融交易数据。
🌐 Web应用程序
该项目现在包括 现代网络界面 使用React+TypeScript+Tailwind CSS构建，提供：
- 拖放文件上传 用于CSV/JSON文件
- 交互式图表 用于支出分析
- 可排序交易表 带过滤功能
- 实时洞察 以及分类置信度得分
- 移动响应式设计
🚀 特性
- 多提供商AI支持：与OpenRouter、OpenAI或任何与OpenAI兼容的API配合使用
- 模型灵活性：通过OpenRouter从各种型号（GPT-4、Claude、Gemini等）中进行选择
- 成本有效：使用较便宜的模型进行基本分类，或使用高级模型进行复杂分析
- 智能分类：AI理解交易上下文，而不仅仅是简单的关键字
- 后备系统：LLM不可用时基于关键字的分类
- 信心评分：每个分类都包括一个置信度得分
- 多种文件格式：支持CSV和JSON文件
- 综合分析：详细的见解，包括支出模式、趋势和细分
- 批处理：高效处理大型交易数据集
📋 先决条件
- Python 3.8或更高版本
- OpenRouter API密钥（推荐）或OpenAI API密钥
- MCP兼容客户端（如Claude/Zed/Cursor）
🔧 安装
- 克隆或创建项目目录:
mkdir finanalyser-mcp
cd finanalyser-mcp- 创建项目结构:
finanalyser-mcp/
├── finanalyser_mcp/
│ ├── __init__.py
│ └── server.py
├── requirements.txt
├── pyproject.toml
└── README.md- 保存Python代码:
- 创建 finanalyser_mcp/__init__.py （空文件） - 将主服务器代码另存为 finanalyser_mcp/server.py
- 创建并激活虚拟环境:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装软件包:
pip install -e .🔑 API提供程序设置
选项1:OpenRouter（推荐）
- 获取API密钥 从 OpenRouter
- 设置环境变量:
export OPENROUTER_API_KEY="your-openrouter-key"- 或通过MCP工具进行配置:
{
"tool": "configure_llm",
"arguments": {
"api_key": "your-openrouter-key",
"base_url": "https://openrouter.ai/api/v1",
"model": "openai/gpt-4o-mini"
}
}选项2:OpenAI Direct
export OPENAI_API_KEY="your-openai-key"选项3：其他OpenAI兼容提供商
{
"tool": "configure_llm",
"arguments": {
"api_key": "your-api-key",
"base_url": "https://your-provider.com/v1",
"model": "your-model-name"
}
}🎯 用法
运行服务器
python -m finanalyser_mcp.server可用型号（通过OpenRouter）
使用 list_available_models 查看热门选项的工具：
成本效益模型：
openai/gpt-4o-mini-15美元/百万代币（建议用于大多数用例）anthropic/claude-3-haiku-0.25美元/百万代币google/gemini-flash-1.5-0.075美元/百万代币
高性能型号：
anthropic/claude-3-5-sonnet-3/10万美元代币（非常适合复杂分析）openai/gpt-4-turbo-10/10万美元代币google/gemini-pro-1.5-1.25亿美元代币
🎯 用法
Web应用程序（推荐）
- 开发模式 （热重新加载）：
# Install dependencies
pip install -r requirements.txt
cd frontend && bun install
# Start both backend + frontend
python run_dev.py然后访问：http://localhost:3000
- 生产模式:
# Build and run
python build_production.py
python -m uvicorn web_api:app --host 0.0.0.0 --port 8000然后访问：http://localhost:8000
MCP服务器（用于CLI/IDE集成）
python -m finanalyser_mcp.server或者，如果已安装：
finanalyser-mcp支持的文件格式
CSV格式
date,description,amount
2024-01-15,Starbucks Coffee,-4.50
2024-01-15,Salary Deposit,3000.00
2024-01-16,Uber Ride,-12.30
2024-01-17,Amazon Purchase,-45.99JSON格式
{
"transactions": [
{
"date": "2024-01-15",
"description": "Starbucks Coffee",
"amount": -4.50
},
{
"date": "2024-01-15",
"description": "Salary Deposit",
"amount": 3000.00
}
]
}🛠️ 可用工具
1. configure_llm
配置LLM提供程序、模型和API设置。
参数：
api_key（字符串，必需）：您的API密钥base_url（字符串，可选）：API基本URL（默认值：OpenRouter）model（字符串，可选）：要使用的模型（默认值：openai/gpt-4o-mini）
例子：
{
"tool": "configure_llm",
"arguments": {
"api_key": "sk-or-v1-your-key",
"base_url": "https://openrouter.ai/api/v1",
"model": "anthropic/claude-3-haiku"
}
}2. list_available_models
列出OpenRouter上可用的热门型号及其定价信息。
例子：
{
"tool": "list_available_models",
"arguments": {}
}3. analyze_financial_file
使用AI驱动的分类从文件中分析财务数据。
参数：
file_path（字符串，必填）：CSV或JSON文件的路径use_llm（布尔值，可选）：是否使用AI分类（默认值：true）
例子：
{
"tool": "analyze_financial_file",
"arguments": {
"file_path": "/path/to/transactions.csv",
"use_llm": true
}
}4. categorize_transactions
将直接提供的交易分类为JSON数据。
参数：
transactions（array，必填）：事务对象数组use_llm（布尔值，可选）：是否使用AI分类（默认值：true）
例子：
{
"tool": "categorize_transactions",
"arguments": {
"transactions": [
{
"date": "2024-01-15",
"description": "McDonald's Drive Thru",
"amount": -8.99
}
],
"use_llm": true
}
}📊 AI分类
该系统使用OpenAI的GPT-4将交易智能地分为以下类别：
费用类别：
- 餐饮
- 运输
- 购物
- 娱乐
- 医疗保健
- 公用事业
- 住房
- 教育
- 个人护理
- 银行和费用
- 保险
- 投资
- 其他
收入类别：
- 薪水
- 自由职业
- 营业收入
- 投资回报
- 租金收入
- 退款
- 礼物
- 其他收入
📈 分析输出
该系统提供全面的分析，包括：
{
"summary": {
"total_transactions": 150,
"total_income": 250000.00,
"total_expenses": 185000.00,
"net_cash_flow": 65000.00,
"date_range": {
"from": "2024-01-01",
"to": "2024-01-31"
},
"categorization_confidence": 0.92
},
"income_breakdown": {
"Salary": {
"amount": 250000.00,
"count": 2
}
},
"expense_breakdown": {
"Food & Dining": {
"amount": 22000.00,
"count": 25
},
"Transportation": {
"amount": 12000.00,
"count": 15
}
},
"monthly_analysis": {
"2024-01": {
"income": 250000.00,
"expenses": 185000.00,
"net": 65000.00
}
},
"top_expenses": [...],
"top_income": [...],
"category_insights": {
"Food & Dining": {
"percentage": 11.89,
"average_amount": 880.00
}
},
"low_confidence_transactions": [
{
"date": "2024-01-15",
"description": "ACME Corp Payment",
"amount": -7500.00,
"category": "Other",
"confidence": 0.3
}
]
}🔍 主要特征说明
人工智能驱动的分类
- 使用GPT-4进行智能交易分析
- 考虑交易金额、描述和上下文
- 为每个分类提供置信度评分
- 批量处理事务以提高效率
后备系统
- AI不可用时自动基于关键字的分类
- 即使没有API密钥，也能确保系统正常工作
- 较低的置信度得分表示回退分类
信心追踪
- 每笔交易都会得到一个置信度分数（0.0到1.0）
- 低置信度交易被标记为手动审查
- 计算总体分类置信度
批处理
- 高效处理大型数据集
- 每个API调用最多处理20个事务
- 失败批次的自动回退
🔧 与Claude整合
要将此MCP服务器与Claude一起使用，请将其添加到MCP配置文件中：
适用于macOS/Linux(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"financial-analyzer": {
"command": "/path/to/your/venv/bin/python",
"args": ["-m", "finanalyser_mcp.server"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
}
}
}
}适用于Windows(%APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"financial-analyzer": {
"command": "C:\\path\\to\\your\\venv\\Scripts\\python.exe",
"args": ["-m", "finanalyser_mcp.server"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
}
}
}
}替代配置（多个提供商）
{
"mcpServers": {
"financial-analyzer": {
"command": "/path/to/your/venv/bin/python",
"args": ["-m", "finanalyser_mcp.server"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-openrouter-key",
"OPENAI_API_KEY": "sk-your-openai-key"
}
}
}
}📝 测试样本数据
创建测试文件 sample_transactions.csv:
date,description,amount
2024-01-01,Salary Deposit,120000.00
2024-01-02,Cafe Coffee Day,-350.00
2024-01-02,Ola to Airport,-850.00
2024-01-03,Amazon Prime Subscription,-1499.00
2024-01-04,Big Bazaar Grocery,-2200.00
2024-01-05,Netflix Monthly,-649.00
2024-01-06,Petrol Pump - HPCL,-3500.00
2024-01-07,Restaurant - Barbeque Nation,-1890.00
2024-01-08,ATM Withdrawal Fee,-25.00
2024-01-09,Freelance Project Payment,45000.00
2024-01-10,Reliance Digital Shopping,-3250.00
2024-01-11,Gym Membership,-2500.00
2024-01-12,Electricity Bill - MSEB,-4200.00
2024-01-13,Doctor Visit Fees,-800.00
2024-01-14,PVR Cinema,-750.00
2024-01-15,House Rent,-25000.00🐛 故障排除
常见问题
- API密钥不工作
- 对于OpenRouter：确保您的密钥以开头 sk-or-v1- - 验证您的API密钥是否正确并且有足够的信用 - 检查型号名称格式（例如。， openai/gpt-4o-mini 适用于OpenRouter）
- 找不到模型错误
- 使用 list_available_models 查看支持模型的工具 - 确保模型名称遵循提供者的命名约定 - 对于OpenRouter，请使用以下格式： provider/model-name
- 文件解析错误
- 检查CSV格式是否与预期列匹配 - 确保金额为数字格式（无货币符号） - 验证文件编码是否为UTF-8
- 分类准确率低
- 尝试一个更强大的模型（例如克劳德3.5十四行诗） - 查看 low_confidence_transactions 在输出中 - 考虑手动查看和更新类别 - 如果可能的话，在交易描述中添加更多上下文
- 性能问题
- 大文件会自动批量处理 - 考虑拆分非常大的文件（>1000个事务） - 监控API速率限制 - 对大型数据集使用更便宜的模型
错误消息
"LLM client not available"：使用配置API密钥configure_llm工具"File not found"：检查文件路径是否正确以及文件是否存在"Unsupported file format"：仅使用CSV或JSON文件"Error parsing CSV/JSON"：检查文件格式和结构"Model not found"：验证您的提供商的型号名称是否正确
💰 成本优化
选择正确的模型
对于基本分类：
google/gemini-flash-2.5-lite（0.075美元/百万代币）-最具成本效益openai/gpt-4o-mini（15美元/百万代币）-成本/性能平衡良好
对于复杂分析：
anthropic/claude-3-haiku（0.25美元/百万代币）-推理良好anthropic/claude-3-5-sonnet（3/10万美元代币）-最高精度
预计成本（1000笔交易）：
- 双子座闪光：~0.01美元
- GPT-4o迷你版：约0.02美元
- 克劳德·海库：约0.03美元
- 克劳德·十四行诗：约0.30美元
批处理优势
- 将API调用减少20倍（每次调用处理20个事务）
- 与单个事务调用相比，显著降低了成本
- 通过上下文批量分析保持高准确性
🔒 安全考虑
- API密钥得到安全处理，不会被记录
- 交易数据在本地处理，只有描述会发送到OpenAI
- 没有永久存储的财务数据
- 考虑在生产中为API键使用环境变量
🚀 高级用法
自定义分类
您可以通过更新来修改代码中的类别 expense_categories 和 income_categories 列表中 FinancialAnalyzer 类。
批量大小调整
修改 batch_size 变量in categorize_transactions_with_llm 方法，每个API调用处理更多或更少的事务。
温度调节
更改 temperature OpenAI API调用中的参数，以使分类或多或少具有创造性（0.0=确定性，1.0=创造性）。
📚 api参考
交易对象结构
@dataclass
class Transaction:
date: str # ISO date format (YYYY-MM-DD)
description: str # Transaction description
amount: float # Transaction amount (+ for income, - for expense)
category: str # AI-assigned category
type: str # "income" or "expense"
confidence: float # Confidence score (0.0 to 1.0)错误处理
所有工具都以一致的格式返回错误消息：
{
"error": "Error message describing what went wrong"
}🤝 贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件。
🆘 支持
如果您遇到问题：
- 检查上面的故障排除部分
- 查看错误消息以获取具体指导
- 确保所有依赖项都已正确安装
- 验证您的OpenAI API密钥是否有效并具有信用
如需更多支持，请在项目存储库中打开问题。