Cashew Expense Tracker MCP Server

An MCP (Model Context Protocol) server that provides access to your Cashew expense tracker SQLite database. This server exposes table schemas as resources, provides tools for running read-only SQL queries, and includes prompts for common data analysis tasks.

Features

- Database Schema Resources: Access complete table schemas and structure information
- Read-only SQL Query Tools: Execute safe SELECT queries against your expense data
- Data Analysis Prompts: Pre-built prompts for common expense analysis tasks
- Multiple Database Support: Switch between test and production databases
- Safety First: Only read-only operations are allowed to protect your data

Installation

The project uses uv for dependency management. Make sure you have uv installed, then run:

uv sync

Usage

Running the Server

Start the MCP server with the test database:

uv run python cashew_mcp_server.py

Use your main Cashew database:

uv run python cashew_mcp_server.py --use-main-db

Use a custom database path:

uv run python cashew_mcp_server.py --db-path /path/to/your/database.sqlite

MCP Client Integration

Claude Desktop

Add the server configuration to your Claude Desktop MCP settings file:

{
  "mcpServers": {
    "cashew-expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "cashew_mcp_server.py"
      ],
      "cwd": "/Users/yash/Developer/cashew-mcp",
      "env": {}
    }
  }
}

VSCode

Add the server configuration to your Vscode workspace's MCP settings file:

{
    "servers": {
        "cashew-mcp-server": {
            "type": "stdio",
            "command": "/Users/yash/Developer/cashew-mcp/.venv/bin/python",
            "args": [
                "/Users/yash/Developer/cashew-mcp/cashew_mcp_server.py",
                "--db-path",
                "/Users/yash/Developer/cashew-mcp/db.sqlite"
            ]
        }
    }
}

MCP Inspector (Development)

Test the server with the MCP Inspector:

uv run mcp dev cashew_mcp_server.py

Available Resources

The server exposes the following resources:

Database Schema Resources

- cashew://schema - Complete database schema for all tables
- cashew://schema/{table_name} - Detailed schema for a specific table

Example tables in your Cashew database:

- wallets - Wallet/account information
- categories - Expense and income categories
- transactions - All financial transactions
- budgets - Budget definitions and limits
- objectives - Financial goals and objectives
- category_budget_limits - Category-specific budget limits

Available Tools

SQL Query Tools

1. execute_sql_query(query: str)
- Execute read-only SELECT queries
- Returns results with columns, rows, and execution metadata
- Safety checks prevent dangerous operations

2. get_table_sample(table_name: str, limit: int = 10)
- Get sample rows from any table
- Useful for exploring data structure
- Limit max 100 rows

3. get_table_count(table_name: str)
- Get total row count for any table
- Quick overview of data volume

Available Prompts

Data Analysis Prompts

1. analyze_spending_patterns
- Comprehensive spending pattern analysis
- Category breakdowns and trends
- Temporal spending patterns
- Budget performance analysis

2. budget_analysis
- Budget performance evaluation
- Budget vs actual spending
- Recommendations for budget adjustments
- Future projections

3. income_vs_expenses
- Income and expense comparison
- Cash flow analysis
- Financial health indicators
- Trend analysis and projections

4. expense_anomaly_detection
- Detect unusual spending patterns
- Identify potential duplicate transactions
- Find spending anomalies and outliers
- Budget violation detection

Example Queries

Here are some example SQL queries you can run using the execute_sql_query tool:

Basic Data Exploration

-- Get recent transactions
SELECT name, amount, date_created, income
FROM transactions
ORDER BY date_created DESC
LIMIT 10;
-- Top spending categories

SELECT c.name, SUM(t.amount) as total_spent, COUNT() as transaction_count

FROM transactions t

JOIN categories c ON t.category_fk = c.category_pk

WHERE t.income = 0

GROUP BY c.name

ORDER BY total_spent DESC

LIMIT 10;

-- Monthly spending summary

SELECT

  strftime('%Y-%m', date_created, 'unixepoch') as month,

  SUM(CASE WHEN income = 0 THEN amount ELSE 0 END) as expenses,

  SUM(CASE WHEN income = 1 THEN amount ELSE 0 END) as income,

  COUNT() as transactions

FROM transactions

GROUP BY strftime('%Y-%m', date_created, 'unixepoch')

ORDER BY month DESC;

Budget Analysis

-- Current budget status
SELECT
  b.name as budget_name,
  b.amount as budget_amount,
  SUM(t.amount) as spent,
  (b.amount - SUM(t.amount)) as remaining,
  ROUND((SUM(t.amount) / b.amount)  100, 2) as percent_used
FROM budgets b
LEFT JOIN transactions t ON t.date_created BETWEEN b.start_date AND b.end_date
  AND t.income = 0
WHERE b.archived = 0
GROUP BY b.budget_pk, b.name, b.amount;

-- Average transaction amount by category
SELECT
  c.name as category,
  ROUND(AVG(t.amount), 2) as avg_amount,
  MIN(t.amount) as min_amount,
  MAX(t.amount) as max_amount,
  COUNT() as transaction_count
FROM transactions t
JOIN categories c ON t.category_fk = c.category_pk
WHERE t.income = 0
GROUP BY c.name
HAVING COUNT(*) >= 5
ORDER BY avg_amount DESC;

Database Schema

Your Cashew database contains the following main tables:

- wallets: Different accounts/wallets for organizing finances
- categories: Income and expense categories with hierarchical structure
- transactions: All financial transactions with amounts, dates, and categorization
- budgets: Budget definitions with time periods and amounts
- objectives: Financial goals and targets
- category_budget_limits: Category-specific budget constraints

Each table includes audit fields like date_created and date_time_modified for tracking changes.

Safety Features

- Read-only Access: Only SELECT queries are allowed
- Query Validation: Dangerous SQL keywords are blocked
- Input Sanitization: All inputs are validated before execution
- Error Handling: Graceful error handling with informative messages

Development

To contribute or modify the server:

1. Install dependencies: uv sync
2. Run tests: uv run python -m pytest (when tests are added)
3. Format code: uv run black .
4. Check types: uv run mypy . (when type hints are added)

Troubleshooting

Common Issues

1. Import errors: Make sure to use uv run to properly activate the virtual environment
2. Database not found: Check the database path and ensure the file exists
3. Permission errors: Ensure the SQLite database file is readable

Debug Mode

Run the server with debug output:

uv run python cashew_mcp_server.py --db-path test.sqlite

The server will output:

- Database path being used
- Available tables found
- Connection status

License

This project is licensed under the MIT License.