finance-agent

🤖 Finance Agent + MCP

!Python !License: MIT !MCP !Tool use

An LLM agent that answers finance questions by calling tools (it never does the math itself), and exposes those same tools as an MCP server so any MCP client — like Claude Desktop — can use them too.

The idea worth stealing: the tools live in one registry and are exposed twice — to the agent loop and to MCP. Define once, no drifting schemas. That's the kind of structure that scales on a team.

✨ Features

• Tool-use agent loop with multi-step tool calls and a printed tool trace.
• MCP server (FastMCP) exposing the same tools to any MCP host.
• Provider-swappable — Anthropic Claude (default) or OpenAI, one env var.
• Deterministic finance tools, unit-tested with no API key.

🧰 Tools

| Tool | What it computes | |---|---| | compound_interest | future value of a lump sum | | cagr | compound annual growth rate (%) | | loan_payment | monthly payment for an amortizing loan | | future_value_of_savings | future value of monthly contributions | | convert_currency | FX conversion (static sample rates) |

🏗️ Architecture

flowchart LR
    R["Shared tool registry<br/>(finagent.tools)"] --- Agent["Agent loop<br/>Claude / OpenAI"]
    R --- MCP["MCP server<br/>(FastMCP)"]
    U[User] --> Agent --> Ans[Answer + tool trace]
    Host["MCP client<br/>(Claude Desktop)"] --> MCP

More in docs/architecture.md.

🚀 Quickstart

# Install (Python 3.10+)
pip install -e .
pip install -r requirements.txt

# Configure
cp .env.example .env       # add ANTHROPIC_API_KEY (or set LLM_PROVIDER=openai)

# Ask the agent (it will call tools and show its work)
python scripts/chat.py "If I save $300/month at 8% for 25 years, how much will I have?"
python scripts/chat.py "Monthly payment on a $250k mortgage at 6.5% over 30 years?"
python scripts/chat.py "Convert 5000 BRL to USD, then grow it at 10% for 5 years."

Example output:

=== Tool calls ===
  • future_value_of_savings({'monthly_contribution': 300, 'annual_rate_pct': 8, 'years': 25}) -> {'future_value': 285809.08, ...}
=== Answer ===
Saving $300/month at 8% for 25 years grows to about $285,809.

🔌 Use it from Claude Desktop (MCP)

Run the server:

python -m finagent.mcp_server

Then add it to your Claude Desktop config (claude_desktop_config.json). Use the Python from the env where you installed the package:

{
  "mcpServers": {
    "finance-agent": {
      "command": "python",
      "args": ["-m", "finagent.mcp_server"]
    }
  }
}

Claude can now call compound_interest, loan_payment, etc. directly.

🗂️ Project structure

finance-agent-mcp/
├── src/finagent/
│   ├── tools.py        # the shared tool registry (pure functions + schemas)
│   ├── agent.py        # provider-swappable tool-use loop
│   ├── mcp_server.py   # exposes the registry over MCP (FastMCP)
│   └── config.py
├── scripts/chat.py     # CLI agent
├── tests/test_tools.py # pure unit tests (no key)
└── docs/architecture.md

✅ Tests

pytest -q     # tests the finance math directly — no API key required

🧭 Roadmap

• [x] Tool registry + 5 finance tools (unit-tested)
• [x] Tool-use agent loop (Claude / OpenAI)
• [x] MCP server exposing the same tools
• [ ] Add a live FX-rate tool + a market-data tool
• [ ] Streaming responses + a small web UI
• [ ] Trace/observability hooks (tie in with project #3)

📄 License

MIT — see LICENSE.

---

Built by Arturio Amorim Sobrinho — AI/LLM Engineer. GitHub · LinkedIn