🤖 Finance Agent + MCP

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