File Parsing Errors

Check your CSV format matches the expected columns
Ensure amounts are in numeric format (no currency symbols)
Verify file encoding is UTF-8

Low Categorization Accuracy

Try a more powerful model (e.g., Claude 3.5 Sonnet)
Review the low_confidence_transactions in the output
Consider manually reviewing and updating categories
Add more context to transaction descriptions if possible

Performance Issues

Large files are processed in batches automatically
Consider splitting very large files (>1000 transactions)
Monitor API rate limits
Use cheaper models for large datasets

Error Messages

"LLM client not available": Configure your API key using the configure_llm tool
"File not found": Check the file path is correct and file exists
"Unsupported file format": Use only CSV or JSON files
"Error parsing CSV/JSON": Check file format and structure
"Model not found": Verify the model name is correct for your provider

💰 Cost Optimization

Choosing the Right Model

For Basic Categorization:

google/gemini-flash-2.5-lite ($0.075/1M tokens) - Most cost-effective
openai/gpt-4o-mini ($0.15/1M tokens) - Good balance of cost/performance

For Complex Analysis:

anthropic/claude-3-haiku ($0.25/1M tokens) - Good reasoning
anthropic/claude-3-5-sonnet ($3/1M tokens) - Best accuracy

Estimated Costs (1000 transactions):

Gemini Flash: ~$0.01
GPT-4o Mini: ~$0.02
Claude Haiku: ~$0.03
Claude Sonnet: ~$0.30

Batch Processing Benefits

Reduces API calls by 20x (processes 20 transactions per call)
Significantly lowers costs compared to individual transaction calls
Maintains high accuracy through contextual batch analysis

🔒 Security Considerations

API keys are handled securely and not logged
Transaction data is processed locally and only descriptions are sent to OpenAI
No financial data is stored permanently
Consider using environment variables for API keys in production

🚀 Advanced Usage

Custom Categorization

You can modify the categories in the code by updating the expense_categories and income_categories lists in the FinancialAnalyzer class.

Batch Size Adjustment

Modify the batch_size variable in categorize_transactions_with_llm method to process more or fewer transactions per API call.

Temperature Adjustment

Change the temperature parameter in the OpenAI API call to make categorization more or less creative (0.0 = deterministic, 1.0 = creative).

📚 API Reference

Transaction Object Structure

@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 Handling

All tools return error messages in a consistent format:

{
  "error": "Error message describing what went wrong"
}

🤝 Contributing

Fork the repository

Categories

Current Category: financial-analysis

finanalyser-mcp

mcp-trader