Maybe Finance MCP Server

A Model Context Protocol (MCP) server that connects Claude Desktop to your self-hosted Maybe Finance instance, enabling natural language financial queries, transaction management, and advanced analytics.

🚀 Features

Complete Financial Management

• Account Management: Query account balances and information
• Transaction CRUD: Create, read, update, and delete transactions
• CSV Import: Bulk import transactions from bank statements
• Smart Search: Find transactions with advanced filtering

Intelligent Categorization

• Auto-Categorization: AI-powered transaction categorization with 17 built-in rules
• Custom Categories: Create and manage your own categories
• Special Categories:
  • Required Purchases (groceries, utilities, etc.)
  • Discretionary Spending
  • Subscriptions
  • Spending but Assets (investments, high-value items)

Advanced Analytics

• Cash Flow Analysis: Track inflows/outflows with insights
• Rolling Metrics: Analyze trends over custom time periods
• Forecasting: Predict future cash flow with confidence intervals
• Spending Breakdowns: Detailed category-based analytics

Prerequisites

• Node.js 20 or later
• Maybe Finance API key (from your self-hosted instance)
• Claude Desktop installed on your computer

Installation

1. Clone this repository:

git clone https://github.com/yourusername/maybe-finance-mcp.git
cd maybe-finance-mcp

2. Install dependencies:

npm install

3. Set up environment variables:

# Create a .env file
cp .env.example .env

# Edit .env with your API credentials
API_BASE_URL=https://your-maybe-instance.com/api/v1
API_KEY=your-api-key-here

4. Build the project:

npm run build

Configuration

Claude Desktop Setup

1. Open Claude Desktop settings
2. Navigate to Developer → Model Context Protocol
3. Add the MCP server configuration:

{
  "mcpServers": {
    "maybe-finance": {
      "command": "node",
      "args": ["C:\\path\\to\\maybe-finance-mcp\\dist\\index.js"],
      "env": {
        "API_BASE_URL": "https://your-maybe-instance.com/api/v1",
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

API Configuration

The MCP server connects to your Maybe Finance instance via its REST API:

# Your Maybe Finance API endpoint
API_BASE_URL=https://your-maybe-instance.com/api/v1

# Your API key (get this from your Maybe Finance settings)
API_KEY=your-api-key-here

The API key should be kept secure and never committed to version control.

📋 Complete Tool Reference

Account Management Tools

get_accounts

List all accounts with balances and net worth calculation.

• Parameters:
  • includeBalance (boolean): Include current balance (default: true)
  • groupByType (boolean): Group accounts by type (default: false)

get_account_balance

Get detailed balance information for a specific account.

• Parameters:
  • accountId (string, required): Account ID

Transaction Management Tools

get_transactions

Retrieve transactions with powerful filtering options.

• Parameters:
  • accountId (string): Filter by account
  • startDate (string): Start date (ISO format)
  • endDate (string): End date (ISO format)
  • category (string): Filter by category
  • limit (number): Maximum results (default: 100)
  • offset (number): Pagination offset

search_transactions

Search transactions by text query.

• Parameters:
  • query (string, required): Search query
  • accountId (string): Limit to specific account
  • limit (number): Maximum results

create_transaction

Create a new transaction.

• Parameters:
  • accountId (string, required): Account ID
  • amount (string, required): Amount (negative for expenses)
  • date (string, required): Transaction date
  • name (string, required): Transaction name/description
  • category (string): Category name
  • merchant (string): Merchant name
  • tags (array): Transaction tags
  • notes (string): Additional notes

update_transaction

Update an existing transaction.

• Parameters:
  • transactionId (string, required): Transaction ID
  • category (string): New category
  • excluded (boolean): Exclude from reports
  • name (string): New name
  • amount (string): New amount
  • date (string): New date
  • merchant (string): New merchant
  • notes (string): New notes
  • tags (array): New tags

categorize_transaction

Categorize a single transaction.

• Parameters:
  • transactionId (string, required): Transaction ID
  • category (string, required): Category name

bulk_categorize

Categorize multiple transactions at once.

• Parameters:
  • transactionIds (array, required): Array of transaction IDs
  • category (string, required): Category name

Cash Flow Analysis Tools

get_cash_flow

Analyze cash flow for a specific period.

• Parameters:
  • days (number): Number of days to analyze (default: 30)
  • accountIds (array): Specific accounts to include
  • includeForecasted (boolean): Include forecasted data

get_rolling_cash_flow

Get rolling cash flow metrics over time.

• Parameters:
  • period (string): Period type (week/month/quarter)
  • periods (number): Number of periods (default: 6)
  • accountIds (array): Specific accounts to include

forecast_cash_flow

Predict future cash flow with confidence intervals.

• Parameters:
  • days (number, required): Days to forecast
  • includeSeasonality (boolean): Consider seasonal patterns
  • confidenceLevel (number): Confidence level (0.8-0.99)

Category Management Tools

get_categories

List all available categories including special categories.

• Parameters: None

create_category

Create a custom category.

• Parameters:
  • name (string, required): Category name
  • parentCategory (string): Parent category for hierarchy
  • color (string): Hex color code
  • icon (string): Icon identifier

get_spending_breakdown

Analyze spending by category.

• Parameters:
  • days (number): Analysis period (default: 30)
  • includeAssets (boolean): Include asset purchases

Import/Export Tools

import_csv

Import transactions from CSV file.

• Parameters:
  • accountId (string, required): Target account ID
  • csvContent (string, required): CSV content
  • encoding (string): base64 or utf8 (default: utf8)
  • fieldMapping (object): Custom field mapping
  • dateFormat (string): Date format in CSV
  • skipDuplicates (boolean): Skip duplicate detection
  • autoCategarize (boolean): Auto-categorize imports
  • dryRun (boolean): Preview without importing

analyze_csv

Analyze CSV structure before import.

• Parameters:
  • csvContent (string, required): CSV content
  • encoding (string): base64 or utf8
  • sampleRows (number): Rows to analyze (default: 5)

Automation Tools

auto_categorize_all

Automatically categorize all uncategorized transactions.

• Parameters:
  • dryRun (boolean): Preview changes (default: true)
  • startDate (string): Process from date
  • overwriteExisting (boolean): Re-categorize existing

get_categorization_rules

View all active categorization rules.

• Parameters: None

💡 Example Usage in Claude

Basic Queries

"What's my current account balance?"
"Show me all transactions from last month"
"How much did I spend on groceries this week?"

Transaction Management

"Create a transaction for $50 coffee shop expense today"
"Update the Netflix transaction to the Subscriptions category"
"Import my bank statement CSV file"

Analytics & Insights

"Show me my cash flow for the last 30 days"
"What are my biggest expense categories?"
"Forecast my cash flow for the next 2 weeks"
"Give me a spending breakdown by category"

Automation

"Auto-categorize all my transactions"
"Show me the categorization rules"
"Bulk categorize all coffee transactions as Dining"

🔧 Development

Run in Development Mode

npm run dev

Run Tests

npm test

Lint Code

npm run lint

🔒 Security Notes

• The MCP server runs locally on your machine
• API credentials are stored in your local environment
• All communication with Maybe Finance is over HTTPS
• The API key provides scoped access to your financial data
• No data is sent to third-party servers
• Sensitive data is never logged or exposed

🐛 Troubleshooting

Connection Issues

• Verify your API endpoint URL is correct
• Check that your API key is valid
• Ensure your Maybe Finance instance is accessible
• Check firewall/proxy settings

Authentication Errors

• Regenerate your API key in Maybe Finance settings
• Check the API key is correctly set in environment variables
• Verify the API key has necessary permissions

Tool Errors

• Ensure account IDs are valid UUIDs
• Check date formats (ISO 8601 preferred)
• Verify category names match exactly
• Check transaction amounts are properly formatted

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments

• Built for Maybe Finance - Open source personal finance app
• Powered by Model Context Protocol
• Designed for use with Claude Desktop