Personal Finance MCP

What JosueM1109/personal-finance-mcp MCP server does

JosueM1109/personal-finance-mcp MCP server gives an MCP client read-only access to financial data retrieved through Plaid. It supports linked bank accounts, credit cards, loans, and brokerage accounts. The project is self-hosted and single-tenant: one deployment is intended for one person, and the server does not provide tools that change account state.

The available data includes account lists and balances, transaction history for up to two years, keyword-based transaction searches, detected recurring inflows and outflows, liabilities, investment holdings, investment activity, and the connection health of linked institutions. Institution status can identify banks that need re-authentication. Each tool returns data along with warnings, allowing a response to report an individual bank or product issue without failing the entire request.

How it works

The application uses Plaid credentials supplied by the operator and access tokens generated when banks are linked. A local link_helper.py web app runs on port 8765 to complete Plaid Link for each institution. After linking, the resulting token is placed in the environment configuration. The main application runs with python server.py and serves the MCP endpoint at http://localhost:8000/mcp.

The MCP client sends tool requests to that HTTP endpoint. The server retrieves and shapes the corresponding Plaid data, rather than storing a separate financial database. The documented client setup uses Claude Code with an HTTP transport. The project also supports Docker deployment and Python hosts, but any publicly reachable deployment needs an authentication layer or private network boundary.

Setup and configuration

Running JosueM1109/personal-finance-mcp requires Python 3.11 or newer, a Plaid account, and an MCP client. The README instructs operators to clone the repository, create a Python virtual environment, install requirements.txt, and copy .env.example to .env. Plaid's free Trial plan is identified as supporting up to 10 Items. The Transactions, Liabilities, and Investments products must be enabled before linking accounts.

Required configuration includes PLAID_CLIENT_ID, PLAID_SECRET, and access-token variables for linked institutions. Tokens are kept in environment variables and .env is intended to remain uncommitted. The documented Claude Code registration command points to http://localhost:8000/mcp. Docker is also available through the repository's included Dockerfile.

Tools and capabilities

The nine read-only tools cover:

• Listing accounts and retrieving current or available balances.
• Getting transactions by date range or searching merchant, name, and counterparty text.
• Finding recurring income and spending streams.
• Reading credit-card, student-loan, and mortgage details, including APR and payment information.
• Reading investment holdings with symbols and security metadata.
• Reading buy, sell, and dividend transactions.
• Checking the health of linked institutions and re-authentication status.

Limitations and notes

This project is not affiliated with Plaid, and the operator remains responsible for Plaid compliance. It does not replace an authentication gateway: exposing the MCP endpoint can expose every linked account and token. The README recommends OAuth 2.1, Cloudflare Access, or a private network for deployments outside localhost.

Data can be empty when the required Plaid products were not enabled before an institution was linked. Some institutions may require registration or re-authentication, and the README specifically notes that unsupported-bank behavior can occur with OAuth institutions. The server is read-only, single-tenant, and intended for personal use rather than shared multi-user access.