Finance-personal-assistant by beprith - MCP Server

Local Financial MCP Mock Server

This project provides a lightweight, local implementation of the Model Context Protocol (MCP) server for simulating financial‑data interactions. It is intended for developers who need a secure, simplified environment for testing applications without connecting to live financial systems or user data.

See README_UI for UI guide

✨ Features

Capability	Description
Dummy Authentication	Login succeeds if the phone number exists as a directory in `test_data_dir/`.
Pre‑canned Financial Data	Static JSON files for net‑worth, credit report, bank & MF transactions, EPF.
Plug‑and‑Play Tools	Each JSON dataset is exposed as an MCP tool (see list below).
Quick setup	Zero external integrations—just clone, install, run.

📂 Directory Layout

.
├── main_mcp.py        # MCP server implementation (Python)
└── test_data_dir      # Dummy data grouped by phone number
    ├── 1111111111
    │   ├── fetch_net_worth.json
    │   └── ...
    └── 2222222222
        ├── fetch_credit_report.json
        └── ...

🔧 Installation & Run

Prerequisites

Python 3.9+

Install dependencies

pip install mcp mcp-inspector

Start the server

python main_mcp.py

The server runs using stdio transport by default.

🔑 Dummy Authentication

Login is successful if the supplied phone number matches a folder in test_data_dir/.
Example valid numbers: 1111111111, 2222222222, 3333333333, … (see folders).

🛠️ Available MCP Tools

Tool Name	Purpose
`authenticate_user`	Dummy login check
`fetch_net_worth`	Net‑worth summary + assets/liabilities
`fetch_credit_report`	Credit score & account details
`fetch_bank_transactions`	Full bank‑statement style transaction list
`fetch_epf_details`	EPF balance & employment history
`fetch_mf_transactions`	Mutual‑fund buy/sell history

All tools accept phone_number as their sole argument.

🚀 FastMCP Dev Environment UI

FastMCP ships with a lightweight developer UI that lets you explore any local MCP server, run tools, and inspect raw responses—all from the browser.

1. Install the FastMCP CLI (one‑time)

pip install fastmcp

2. Launch the Dev UI

From your project root:

fastmcp dev main_mcp.py

⚙️ This spins up main_mcp.py and the web UI in one command.

Already registered the server in mcp_servers.json? Simply run:

fastmcp dev

FastMCP will auto‑detect local-financial-mcp and start it.

The UI opens at http://localhost:4400 where you can:

Authenticate with any test phone number (e.g., 2222222222).
Invoke tools like fetch_net_worth, fetch_credit_report, etc.
Inspect request/response JSON in real time for quick debugging.

3. Use alongside other FastMCP‑aware apps

The Dev UI acts purely as a client—you can keep it open while calling the same server from Langflow or the FastMCP CLI.

⚙️ FastMCP Server‑side Entry

If you want another FastMCP‑aware application (or CLI) to auto‑launch this mock server, add the following stanza to its mcp_servers.json (or similar) file:

{
  "servers": {
    "local-financial-mcp": {
      "transport": "stdio",          // or "sse" if you expose an HTTP endpoint
      "command": "python",
      "args": ["main_mcp.py"],
      "cwd": "<path-to-project-root>"  // folder containing main_mcp.py & test_data_dir/
    }
  }
}

transport – Use stdio for the default pipe transport (fastest). Switch to sse if you wrap the server with an HTTP layer and expose /mcp/stream.
cwd – Ensures relative paths (like test_data_dir/) resolve correctly.

Once registered, you can invoke tools directly via FastMCP CLI:

mcp call local-financial-mcp authenticate_user --phone_number 2222222222
mcp call local-financial-mcp fetch_net_worth --phone_number 2222222222

🧑‍💻 Example Workflow

mcp.call("authenticate_user", phone_number="2222222222")
print(mcp.call("fetch_net_worth", phone_number="2222222222"))

🤝 Contributing

Pull requests are welcome—whether it’s extra dummy scenarios, bug fixes, or new tools.

🪪 License

This project is provided as‑is for educational and testing purposes.