Finance Agent

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

• Tool registry + 5 finance tools (unit-tested)
• Tool-use agent loop (Claude / OpenAI)
• 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