MCP Server

Connect Finance AI to your favorite AI tools using the Model Context Protocol. Query your accounts, transactions, net worth, and more — right from Claude Code, Claude Desktop, ChatGPT, or any MCP-compatible client.

Getting Started

  1. Go to your Account page and find the MCP Server section.
  2. Click New Key to create an API key. Copy it — you'll only see it once.
  3. Add the server URL and API key to your MCP client using the instructions below.

Connecting Your Client

Claude Code (CLI)

Add the MCP server to your project or global configuration:

claude mcp add finance-ai \
  --transport http \
  --url https://aipersonalfinance.app/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Or add it to your .mcp.json file:

{
  "mcpServers": {
    "finance-ai": {
      "type": "url",
      "url": "https://aipersonalfinance.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop / Claude Cowork

Open Settings → Developer → MCP Servers and add a new server:

{
  "mcpServers": {
    "finance-ai": {
      "type": "url",
      "url": "https://aipersonalfinance.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

ChatGPT

In ChatGPT, go to Settings → Connected Apps → Add MCP Server:

  1. Enter the server URL: https://aipersonalfinance.app/api/mcp
  2. Set the authentication type to Bearer Token
  3. Paste your API key as the token

Cursor, Windsurf & Other MCP Clients

Most MCP clients support HTTP transport. Add a server with these details:

URLhttps://aipersonalfinance.app/api/mcp
TransportStreamable HTTP
Auth HeaderAuthorization: Bearer YOUR_API_KEY

Refer to your client's documentation for the exact configuration format. The server follows the MCP Streamable HTTP transport specification.

Available Tools

The MCP server exposes the following tools. Your AI assistant will automatically discover and use them.

getAccounts

Get all bank, credit, and investment accounts with current balances and types.

Returns account name, type (depository, credit, investment, loan), subtype, current/available balance, credit limit, and masked account number.

query

Run a read-only SQL query against any of your user_* views.

Execute PostgreSQL SELECT queries against pre-filtered views of your data (transactions, categories, rules, accounts, stocks, mortgages, etc.). Supports pagination (50 rows/page). Only SELECT/WITH statements are allowed — your data is safe. Call getSchema first to see every available view and column.

Parameters
sql(string)A SELECT/WITH query against any user_* view
page(number)Page number for pagination (optional, default: 1)
getNetWorth

Calculate current net worth from all accounts, stocks, and mortgages.

Returns total assets, liabilities, net worth, and a breakdown by category (bank accounts, investment accounts, credit/loans, manual stocks, mortgage equity).

getManualStocks

Get all manually tracked stock and equity holdings.

Returns stock name, ticker, shares, price per share, strike price, exercise status, gross value, and net value for each holding.

getMortgages

Get all mortgage and property records.

Returns property name, home value, loan amount, equity, loan-to-value ratio, and interest rate for each mortgage.

getCategories

Get all custom transaction categories.

Returns category name, emoji icon, and color for each user-created category.

categorizeTransactions

Assign a custom category to transactions matching filters.

Categorizes matching transactions and creates merchant rules for future auto-categorization. Creates the category if it doesn't exist.

Parameters
categoryName(string)Category name (created if it doesn't exist)
search(string)Filter by transaction/merchant name (optional)
primaryCategory(string)Filter by Plaid category (optional)
dateFrom(string)Start date filter (optional)
dateTo(string)End date filter (optional)
limit(number)Max transactions to categorize (optional, default: 200)
generateChart

Generate structured chart data for visualizing financial data.

Returns structured data for bar, pie, line, or area charts. Best used after querying transaction data to visualize spending breakdowns, trends, or comparisons.

Parameters
chartType("bar" | "pie" | "line" | "area")Type of chart
title(string)Chart title
data(array)Array of { name, value } data points
valuePrefix(string)Value prefix, e.g. "$" (optional)
valueSuffix(string)Value suffix, e.g. "%" (optional)

Security

  • API keys are hashed with SHA-256 before storage — we never store your raw key.
  • Each key is scoped to your account. The MCP server can only access your data.
  • Transaction queries are read-only. Only SELECT statements are allowed, with a 5-second timeout.
  • You can revoke a key at any time from Settings. Access is terminated immediately.
  • All requests are served over HTTPS. The server follows the MCP specification for authentication.

Troubleshooting

I get 'Unauthorized' when connecting
Make sure your Authorization header is set to 'Bearer YOUR_API_KEY' (with the 'Bearer ' prefix). Double-check you copied the full key including the 'fai_' prefix.
Tools aren't showing up
Ensure your client supports MCP Streamable HTTP transport. Some clients may need a restart after adding a new server.
Queries return empty results
The transaction view only includes synced transactions. Make sure you've connected bank accounts and they've completed their initial sync.