Skip to main content
Glama
financial-research-mcp

financial-research-mcp

by heyhumayun

Multi-Agent Financial Research with MCP

Abstract

This project implements a bounded, auditable financial-research workflow. A supervisor routes a question to specialist agents, tools collect evidence through a local gateway or Model Context Protocol (MCP) transport, and a critic reviews coverage before a research brief is produced. A labelled offline benchmark evaluates routing, tool selection, evidence linkage, failure handling, and latency. The system is a research-assistance prototype; it does not execute trades or establish investment alpha.

Related MCP server: Aegis Risk

Research objectives

  • Evaluate whether specialist-agent orchestration selects appropriate tools and evidence for financial-research questions.

  • Compare deterministic orchestration with optional local-LLM reasoning on the same labelled cases.

  • Make provider failures, offline fallbacks, source links, and execution traces visible in the final report.

  • Separate software-workflow quality from the factual and financial validity of a research conclusion.

Data

Live adapters can request market data from yfinance, news from Yahoo Finance RSS, papers from arXiv, and reported fundamentals from SEC Company Facts. Optional market and news providers require their respective credentials. Local documents can be searched with a token-vector retriever or optional sentence-transformer/FAISS retrieval.

The reproducible offline mode uses packaged deterministic fixtures, including synthetic market, news, and paper records and demonstration fundamentals. The 30-case evaluation set contains project-authored labels for required agents, tools, evidence categories, contradictions, and failure conditions. Neither the fixtures nor the labels are a point-in-time financial dataset or independently adjudicated analyst judgments.

Methodology

The supervisor selects a bounded set of market, news, fundamentals, comparison, research, document, and risk specialists. Specialists call typed tools and attach evidence identifiers to their findings. A critic checks configured coverage, fallback, and contradiction conditions; the supervisor may make one evidence-recovery pass. Synthesis produces a brief, structured output, and an execution trace. Optional Ollama reasoning can assist planning and synthesis; deterministic behavior remains available without an LLM.

The tool gateway supports direct local calls, an in-process MCP-shaped compatibility mode, and a real MCP client/server subprocess over stdio. Only mcp-stdio crosses an MCP transport boundary. Saved runs contain report.md, report.json, and trace.json under runs/<run_id>/.

Experimental setup

The primary evaluation is a 30-case deterministic offline benchmark. It measures routing and tool selection, citation coverage, claim-to-evidence linkage, contradiction and critic detection, fallback behavior, and stage-level latency. A separate six-case, category-stratified ablation compares deterministic orchestration with local llama3.2:3b reasoning. Failure-injection tests cover unavailable providers, malformed MCP responses, unavailable Ollama, stale fixtures, and contradictory findings. See EVALUATION.md for definitions and protocol details.

Results

The recorded offline benchmark from 2026-08-31 reported:

Metric

Result

Overall benchmark score

0.9799

Routing precision / recall

1.0000 / 1.0000

Tool-selection accuracy

1.0000

Citation coverage

0.9189

Claim-to-evidence support

0.9716

Contradiction recall

1.0000

Critic detection rate

1.0000

In the six-case local-model ablation, the deterministic and Ollama configurations scored 0.9668 and 0.9407, respectively. Exact-route rate fell from 1.0000 to 0.5000 with Ollama, while mean end-to-end latency rose from 0.98 ms to 50,679 ms in that sample. These are software-workflow measurements, not estimates of trading or investment performance.

Limitations

  • Offline fixtures are synthetic, and the project-authored labels lack independent analyst adjudication.

  • Live public sources may be delayed, rate-limited, incomplete, or unavailable; fallback data is explicitly marked.

  • Evidence identifiers establish source linkage, not excerpt-level entailment or factual correctness.

  • Headline sentiment, confidence values, and deterministic query routing are heuristics rather than calibrated financial models.

  • The six-case LLM ablation is too small for a general model-quality conclusion; offline latency is not representative of live providers.

  • The system does not implement point-in-time market-data controls, portfolio construction, execution, or financial outcome validation.

Repository structure

src/financial_research_agent/
  agents/          supervisor, specialists, critic, and synthesis
  mcp/             tool contracts and stdio server
  tools/           provider adapters, retrieval, and risk calculations
  data/            packaged fixtures and evaluation cases
  benchmark.py     labelled workflow evaluation
  cli.py           command-line interface
  api.py           FastAPI interface
  ui.py            Streamlit interface
tests/             unit and integration tests
EVALUATION.md      evaluation protocol and recorded measurements
PRODUCT_READINESS.md  capability and deployment-gap assessment

Installation

Python 3.10 or newer is required.

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev,api,ui,market]"

The optional rag extra installs sentence-transformer and FAISS dependencies. Live providers and Ollama are not required for the offline workflow.

Usage

Run an offline investigation through the real MCP transport:

FIN_RESEARCH_LIVE=0 FIN_RESEARCH_TOOL_RUNTIME=mcp-stdio \
  financial-research-agent "Assess NVDA AI infrastructure risk and research" --save

Run the recorded evaluation procedure and repository checks:

FIN_RESEARCH_LIVE=0 financial-research-eval
ruff check src tests
python3 -m unittest discover -s tests -v

financial-research-api, financial-research-ui, and financial-research-mcp start the API, Streamlit interface, and standalone MCP server. Live-provider mode may require API credentials; use FIN_RESEARCH_OFFLINE_FALLBACK=0 to fail when a live source is unavailable instead of accepting fixture fallback.

References

Available Tools

10 tools
calculate_max_drawdownA

Calculate maximum drawdown from prices.

Inputs: prices (required). Returns: result

calculate_returnsB

Calculate log returns from a price series.

Inputs: prices (required). Returns: result

calculate_volatilityA

Calculate rolling volatility from prices.

Inputs: prices (required), window, annualize. Returns: result

get_company_fundamentalsC

Get reported company facts with provider provenance.

Inputs: ticker (required), provider.

get_market_dataC

Get recent market bars together with provider provenance.

Inputs: ticker (required), days, provider.

search_arxivC

Search research papers together with provider provenance.

Inputs: query (required), limit, provider.

search_documentsC

Search local research documents.

Inputs: query (required), limit. Returns: result

search_documents_semanticB

Search local research documents with FAISS embeddings when available.

Inputs: query (required), limit. Returns: result

search_documents_vectorB

Search local research documents with vector-space ranking.

Inputs: query (required), limit. Returns: result

search_newsB

Search financial news together with provider provenance.

Inputs: query (required), limit, ticker, provider.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 10 tools

    Disambiguation3/5

    Most tools map cleanly to distinct resources or calculations, but the three search_documents variants overlap considerably and an agent may struggle to choose between plain, vector, and semantic search. Descriptions help somewhat, but the boundaries remain unclear.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern: get_*, search_*, and calculate_*. This makes tool selection predictable and reinforces the purpose of each tool.

    Tool Count4/5

    Ten tools is a reasonable size for a financial research server covering data retrieval, document search, and analytics. The three document search variants add mild redundancy but do not make the count excessive.

    Completeness4/5

    The tool surface covers core research workflows: retrieving market data and fundamentals, searching news/papers/local documents, and computing common return and risk statistics. Minor gaps exist, such as no explicit save/annotate workflow or more advanced analytics, but these are not critical for the apparent scope.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.

      https://mcp.ko.io/mcp
    • Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.

      https://helveticresearch.com/mcp
    • Finance research agent for thesis, trade note, and market-state review.

    • Your agent needs markets — prices and fundamentals for listed companies, the filings behind them, crypto, and what the prediction markets put the odds at. **What you can ask for** • "Pull this company's income statement, cash flow and balance sheet for the last 8 quarters." • "What did insiders buy or sell, and when?" • "Snapshot prices for these 50 tickers, then the OHLC history for the three that moved." • "What are the current odds on this event across Kalshi and Polymarket?" • "Screen for companies matching these financial criteria." **How to use it** Point any MCP client at https://mcp.aisa.one/finance/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: prices and snapshots, income statements, balance sheets and cash flows, metrics and ratios, earnings and analyst estimates, filings and line-item search, insider trades, macro interest rates, news, a screener; CoinGecko spot prices, market tables, OHLC, per-venue tickers and trending; Kalshi and Polymarket markets and trades; plus EDINET filings for Japan. **Why this rather than the source** Equities, crypto and event markets behind one account, so a cross-asset question is one conversation. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Read the number here, then ask the same agent what X is saying about the ticker today — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/marketpulse/mcp · /crypto-market-data/mcp · /prediction-market-data/mcp · /stock-pulse/mcp for one slice each.

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to operate a local financial terminal, including market data, backtesting, paper portfolio management, and news digest, through safe, gated tools over MCP.
      6
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A multi-agent financial portfolio risk analyzer that provides MCP tools for fetching market news and storing compliance-reviewed assessment reports in a local database.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Provides multi-agent equity research for US markets with provenance-backed financial data from SEC EDGAR, technicals, macro, and Alpaca paper trading, enforcing risk limits and journaling theses.
      27
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables natural-language, source-backed research across SEC filings, earnings transcripts, company financials, stock and crypto market data, and prediction markets news. It also provides deep research orchestration and live documentation access through MCP clients.
      -