quicken-mcp-server

sgoley/quicken-mcp-server

3.3

If you are the rightful owner of quicken-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Quicken MCP Server is a containerized solution that transforms Quicken QIF files into a queryable DuckDB database, enabling interaction with financial data through standardized MCP tools.

Tools
6
Resources
0
Prompts
0

Quicken MCP Server

A containerized MCP (Model Context Protocol) server that converts a local export of Quicken in Quicken Interchange Format (QIF) files into a queryable DuckDB database, exposing financial data through standardized MCP tools to LLM Clients.

Features

  • QIF Import: Parse and normalize Quicken QIF files into structured database tables
  • In-Memory Database: Uses DuckDB for fast, SQL-compatible data access
  • MCP Tools: Exposes financial data through standardized MCP tools including:
    • list_accounts - List all accounts with balances
    • list_transactions - Query transactions with flexible filtering
    • run_sql - Execute safe SQL queries against the data
    • get_summaries - Generate financial summaries and statistics
    • get_categories - List transaction categories
    • search_transactions - Search transactions by text
  • Multiple Transports: Supports both stdio and Server-Sent Events (SSE) protocols
  • Security: SQL queries are restricted to SELECT operations only
  • Resources: Export data as CSV files through MCP resources

TLDR: Talk to your Quicken data in ChatGPT, Claude or ollama!

Quick Start

Using Docker (Recommended)

  1. Build the container:

    docker build -t quicken-mcp-server .

  2. Register the MCP in your LLM client config

    Example of claude-desktop-config.json entry:

        "quicken-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "<path>/data:/data:ro",
        "quicken-mcp-server",
        "--qif",
        "/data/personal-data.qif"
      ],
      "env": {}
    }

    In this example, I have exported my quicken data into the QIF format and named it "personal-data.qif". I then placed it into a folder called "data" and made that folder available to the docker image as a volume also named "data".

Local Development

  1. Install dependencies:

    pip install -r requirements.txt

  2. Run locally:

    python -m app.main --qif /path/to/your/file.qif

Usage Examples

Command Line Options

python -m app.main --help

Required:

  • --qif PATH - Path to the QIF file to load

Optional:

  • --server-mode {stdio,sse} - Transport mode (default: stdio)
  • --listen HOST:PORT - Listen address for SSE mode (default: 127.0.0.1:8700)
  • --log-level {DEBUG,INFO,WARNING,ERROR} - Log level (default: INFO)
  • --memory-limit SIZE - DuckDB memory limit (default: 8GB)

Environment Variables

You can also configure using environment variables:

  • QIF_PATH - Path to QIF file
  • SERVER_MODE - Transport mode
  • LOG_LEVEL - Logging level
  • MEMORY_LIMIT - Memory limit

Docker Examples

Basic usage with bind mount:

docker run --rm \
  -v "$PWD/data:/data:ro" \
  --network host \
  quicken-mcp --qif /data/example-file.qif

SSE mode with custom port:

docker run --rm \
  -v "$PWD/data:/data:ro" \
  -p 8700:8700 \
  quicken-mcp \
  --qif /data/example-file.qif \
  --server-mode sse \
  --listen 0.0.0.0:8700

MCP Tools Reference

list_accounts

Returns all accounts with metadata:

{
  "success": true,
  "accounts": [
    {
      "account_id": 1,
      "name": "Checking Account",
      "type": "Bank",
      "balance": 1234.56
    }
  ]
}

list_transactions

Query transactions with optional filters:

{
  "account_type": "Bank",
  "date_from": "2023-01-01",
  "date_to": "2023-12-31",
  "category": "Food",
  "limit": 50
}

run_sql

Execute SELECT queries:

{
  "query": "SELECT category, SUM(amount) FROM transactions WHERE date >= '2023-01-01' GROUP BY category ORDER BY SUM(amount) DESC LIMIT 10"
}

get_summaries

Generate financial summaries:

{
  "period": "month"  // Options: "month", "category", "account", "all"
}

Database Schema

The server creates the following tables:

  • accounts - Account information (name, type, balance, etc.)
  • categories - Transaction categories and metadata
  • transactions - Individual transactions
  • transaction_splits - Split transaction details

Plus useful views:

  • transactions_with_categories - Transactions joined with category info
  • monthly_summaries - Monthly spending summaries
  • category_summaries - Category-wise summaries

MCP Client Integration

Testing with MCP Inspector

The MCP Inspector is a powerful debugging tool for testing MCP servers. You can use it to explore available tools, test queries, and debug issues.

Using Docker (Recommended):

# Start the inspector (runs on http://localhost:5173)
docker run --rm --network host -p 5173:5173 ghcr.io/modelcontextprotocol/inspector:latest

Then connect to your server:

  • Stdio mode: Use command docker run --rm -v "/path/to/your/qif:/data:ro" --network host quicken-mcp --qif /data/yourfile.qif
  • SSE mode: Use URL http://127.0.0.1:8700/sse

Using npx (Local Development):

# For stdio mode
npx @modelcontextprotocol/inspector docker run --rm -v "/path/to/your/qif:/data:ro" --network host quicken-mcp --qif /data/yourfile.qif

# For SSE mode, start the server first, then:
npx @modelcontextprotocol/inspector http://127.0.0.1:8700/sse

With mcpm (MCP Manager)

Create an mcpm profile:

mcpm profile create quicken-ledger
mcpm profile edit quicken-ledger --add local::quicken-mcp

With MCP-compatible editors

Configure your editor to use this server:

  • Stdio mode: Point to the docker run command
  • SSE mode: Use http://127.0.0.1:8700/sse endpoint

Security Considerations

  • QIF files should be trusted and local
  • SQL execution is restricted to SELECT statements only
  • Dangerous SQL keywords are blocked
  • Container runs as non-root user
  • File access is controlled through bind mounts

Performance

  • Recommended memory limit: 8GB for large datasets
  • File size warning at 100MB+
  • Query results limited to prevent memory issues
  • DuckDB provides excellent analytical performance

Development

Project Structure

quicken-mcp-server/
ā”œā”€ā”€ app/
ā”‚   ā”œā”€ā”€ __init__.py
ā”‚   ā”œā”€ā”€ config.py          # Configuration management
ā”‚   ā”œā”€ā”€ qif_loader.py      # QIF parsing and database loading
ā”‚   ā”œā”€ā”€ schema.sql         # Database schema definitions
ā”‚   ā”œā”€ā”€ mcp_tools.py       # MCP tool implementations
ā”‚   ā”œā”€ā”€ server.py          # MCP server setup
ā”‚   ā””ā”€ā”€ main.py           # Application entry point
ā”œā”€ā”€ tests/
ā”œā”€ā”€ Dockerfile
ā”œā”€ā”€ pyproject.toml
ā”œā”€ā”€ requirements.txt
ā””ā”€ā”€ README.md

Running Tests

pytest

Code Quality

ruff check .
mypy app/

License

MIT License - see LICENSE file for details.