Quant Brain MCP

A model-independent local company research desk, with evidence-backed workflows through MCP.

Connect Claude, GPT, Gemini or a local model through an MCP-capable client. The core server does not require a model account or inference SDK. See the client connection guide and self-host operations. The separate Codex background research workflow is optional and requires its own setup. For local, VPS and Render hosting, follow the MCP-only deployment guide.

Browse the documentation index or repository layout for the Python services, tools, tests, examples and operator scripts.

Run the MCP research server

Use Python 3.12. The core research tools need no model account, broker or hosted database. Models access them through an MCP-capable client:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip install --require-hashes -r requirements_filing.lock
python scripts/setup_research_desk.py
source .quant-brain/research-desk.env
python fastmcp_server.py

Connect a local client to the authenticated endpoint at http://127.0.0.1:8000/mcp, or use the canonical stdio launcher in the client guide. For a research view inside a model client, select the optional company_dashboard MCP prompt or use the natural-language request guide. The prompt returns instructions for using the existing tools; it does not run a web interface, fetch new sources or send a model request. Presentation depends on the client.

Keep the generated configuration private. See operator controls for storage, backups, source permissions and the separate filing worker.

The Next.js dashboard is deferred and excluded from this change. The existing Streamlit interfaces remain optional legacy entry points. The research desk guide describes their setup and the underlying MCP workflows. For an offline CLI journey, install the documented desk profile and run python scripts/demo_research_desk.py.

Each self-hosting user supplies their own SEC contact locally. SEC setup is optional: run python scripts/setup_research_desk.py --configure-sec, then source the generated .quant-brain/research-sec.env alongside research-desk.env before starting the dashboard, MCP or filing worker. No contact is bundled in the project or required for offline tools.

US discovery targets recent SEC filings; reviewed official document URLs can also be configured for US or Indian issuers. These links cover only the documents supplied and do not themselves discover new issuer URLs. Configured official RSS/Atom feeds now discover supported new reports, including NSE integrated financial XBRL. The official issuer directory supplies searchable metadata; financial coverage requires successfully imported supported reports. Saved copies can be used explicitly when an eligible retrieval fails, with their age and degraded status shown. See filing reliability for setup and limits. Optional PDF repair, local password-based decryption, and review-only OCR are described in PDF preprocessing.

The NSE archive route passed a real TCS quarterly filing through authenticated MCP, including 12 extracted facts and retained-original verification. Its graphical rupee label requires explicit, warned INR confirmation. SEC, Microsoft and Infosys routes returned HTTP 403 here. Apple report retrieval succeeded, but its mixed quarterly/annual PDF layout is refused; US structured filing support is separate. Coverage remains bounded to supported formats and configured documents. No paid competitor data is scraped or bundled.

Automated NSE/BSE requests are now disabled by default. Upload permitted reports or configure exchange access only when separately authorized. The local dashboards are pinned to loopback; telemetry is opt-in. See the review fixes and limits and operator controls.

Saved assumptions and changes

Thesis Watch turns selected financial assumptions into reproducible checks. Register a revenue-growth floor or a margin threshold against saved financial facts, then evaluate a later disclosure. The report shows new breaches, recoveries, missing evidence, exact arithmetic and source locations. Definitions and dated checkpoints persist in owner-scoped SQLite; repeating a checkpoint is idempotent. This closes the basic "what changed in my thesis?" loop without a paid model.

Try the clearly labelled synthetic journey after installing requirements.txt:

python scripts/demo_thesis_watch.py

It demonstrates holding → breached → holding → incomplete. To use the four new tools on the authenticated server, enable QUANT_THESIS_ENABLED=1 and follow the Thesis Watch setup and MCP example. Checks run when called or by a configured filing worker. SEC discovery and recurring local checks are implemented; Telegram/email delivery and broader issuer discovery remain future work. Source extraction and caller-supplied facts remain unverified; "holding" means the selected numeric rules passed, not that an investment is safe.

Start with the authenticated server and its 66 tools. Follow the local MCP setup to install dependencies, generate a private token and launch it. Then run python smoke_test.py --live from a second configured terminal to verify real quotes, company data, indicators, the SMA backtest and historical risk scenarios through MCP. No dashboard, paid model or brokerage account is needed for that workflow.

The original backtests now fill completed-bar signals at the next bar's open, reject insufficient history clearly, and return null for unavailable metrics. See the original-server repair checks.

Original MCP server

Quant Brain combines 25 market tools with four research-job tools, five financial-fact tools, three filing tools, four thesis tools and twenty-five company-research tools (66 in total). Ask for a quote, run a backtest, inspect historical risk distances, or start an Indian-equity research job that coordinates Codex specialists and returns evidence, disagreements, and an execution trace. An MCP-capable client can present the report using its chosen model.

Related MCP server: vibetrader-mcp

Current capabilities and target design

The extended backend provides market calculations, optional NSE agent research and bounded India/US filing comparisons. Its annual Earnings Evidence workflow accepts a document and supported financial question, discovers primary statements in large text PDFs, and saves source-linked arithmetic and review flags. See the filing-to-answer workflow for document inputs, source locations, compatibility checks and evidence exports. The next architecture extends that foundation into a global research desk with browser investigation, broader evidence verification, and wider-market monitoring. Those extensions are planned; they are not activated by installing the current release.

See the target architecture and delivery roadmap.

Recent reliability improvements include separate internal stream/calculation limits, explicit financial units, reproducibility metadata for all indicators, and report downgrades for failed calls or unavailable source documents. See validation results and the VPS update procedure.

How the current version works

flowchart TB
    User["You"] --> Claude["Claude / MCP client"]
    Claude -->|"Bearer-authenticated HTTP"| Outer["Quant Brain MCP<br/>25 market + 4 research tools"]
    Outer -->|"Direct market requests"| Engines["Calculation engines"]
    Outer -->|"Background research job"| Worker["Codex research roles"]
    Worker --> Search["Live web search"]
    Worker -->|"Separate internal token"| Inner["Private MCP<br/>22 read-only tools"]
    Inner --> Engines
    Engines --> Data["Yahoo Finance / yfinance"]
    Worker --> Report["Evidence + review + execution trace"]
    Report -->|"Poll and retrieve"| Claude
    Claude --> Answer["Answer with sources and limitations"]

The optional research runtime runs on the same host as the MCP servers, either a personal computer or a VPS. It uses Codex's supported sign-in flow; credentials stay with the runtime. Claude receives a separate MCP bearer token. No Google login is required. There is no order execution.

Start here

The optional six-role Codex workflow requires its own supported login and model access; those costs are separate from the free workbench. For that research setup, install Python 3.12 dependencies with python -m pip install -r requirements_research.txt, then follow the research setup guide to generate private tokens, start both servers, and connect Claude. The base market server only needs requirements.txt.

Claude Code can reach your local HTTP endpoint. Claude Desktop/web remote connectors connect from Anthropic's cloud and need a reachable HTTPS endpoint; they cannot reach your computer's localhost. Local Desktop stdio integrations are a separate connection method and are not configured by this research setup.

The existing hosted endpoint is https://mcp-quant-brain.onrender.com/mcp. It requires an operator-issued bearer token. Its deployed version, research configuration, and Codex sign-in must be checked separately; a GitHub push or successful CI run does not verify that hosted deployment.

The six research roles

See the agent and tool map for inputs, outputs, exact tool names, current shared permissions, and proposed specialist permissions.

Company and quant work run in parallel. Quick uses four roles/calls; standard adds the lead and skeptic with up to one correction round (6–8 calls); deep permits two correction rounds (6–10 calls). Calls and jobs have timeouts. Reports persist in owner-scoped SQLite storage; clients poll rather than hold a single HTTP request open. LangGraph orchestrates the research roles: company and quant run in parallel, then review and bounded correction precede synthesis. It runs locally inside the backend; no LangGraph cloud account is needed. SQLite stores jobs and reports; automatic graph crash-resume is not enabled. See the workflow and lifecycle diagrams. Separate jobs execute one at a time; parallel role execution does not mean unlimited simultaneous research jobs.

Target global research workflow

This diagram describes proposed components, not the current tool catalog.

flowchart TD
    Q["Question or monitored event"] --> Plan["Plan tasks and budget"]
    Plan --> F["Filing and browser research"]
    Plan --> A["Quant, valuation, macro and portfolio analysis"]
    Providers["Market and disclosure adapters"] --> Gate["Instrument, time, currency and freshness checks"]
    Gate --> F
    Gate --> A
    F --> E["Captured evidence and calculation records"]
    A --> E
    E --> Review["Deterministic validation, skeptic and auditor"]
    Review --> Report["Cited report with unresolved disagreements"]
    Report --> Client["Claude or another MCP client"]
    Report --> Memory["Thesis history and change monitoring"]
    Memory --> Q

Independent investigations run in parallel; review follows their results. Simple requests go directly to calculation tools. The planned browser worker investigates documents and websites; a market-data adapter supplies quotes and candles.

Example request supported by the current version:

Use Quant Brain to run quick research on TCS.NS. Check the latest available quote and company disclosures. Poll until finished, retrieve the report, and give your judgment with source dates, uncertainties, and disagreements.

What you can use it for

From a question to an answer

1. Claude calls start_research with your question, 1–5 NSE symbols, and a depth.

2. Quant Brain returns a job ID and runs the specialists in the background.

3. Claude polls get_research_status, then fetches get_research_report.

4. Claude uses the evidence, audit warnings, and execution trace to explain its judgment.

Use cancel_research to stop an owned job. A completed job can still report insufficient_evidence; successful execution does not imply a confident answer. For direct calculations, Claude calls the market tools without starting agents.

Tools

All 66 tool names, parameters, and response conventions are documented in the tool reference. The internal research MCP exposes only 22 read-only tools; alerts, charts, and research orchestration are excluded.

Validation and limits

The current review-fix release passed 1,578 local tests, with three optional skips, and 292 tests in a fresh hash-locked desk installation. All 18 retained real India/US filing checks were enabled. Protocol, native PDF, source retention, privacy, units and dashboard exposure checks passed. See the review resolution and validation report.

The earlier 29 October reliability milestone added failure/recovery checks, retained-original verification, source revision guards and supported Indian interim extraction. At that revision, a real NSE TCS filing passed through the authenticated MCP with its then-current 55 tools, and all 18 retained real India/US filing checks passed. The offline fallback/outage/recovery demo runs in both installation profiles. See the release checks and filing reliability for current results and limits.

The earlier 29 October Thesis Watch release passed 1,268 tests, with 21 optional integration skips, plus 24 thesis tests in the lean demo environment. The synthetic journey passed through the running authenticated MCP over HTTP, and the original six-call live market check also passed. The checks cover the deterministic engine, persistence, filing-to-thesis and MCP/HTTP paths. See Thesis Watch for the exact supported scope. These checks do not validate a hosted deployment or automatic monitoring.

The October 2026 workbench release passed 1,219 tests locally, with 21 explicit integration skips, plus 47 tests in a clean demo-only environment. The actual browser save flow, stdio MCP calls, real chart export, and a Yahoo history download were also exercised. See demo validation for commands, exact scope, and remaining limitations.

An earlier alert/reliability milestone passed 379 tests, including PostgreSQL and VPS updater rollback checks, plus HTTP and real PNG export smoke tests. A quick Codex research job completed with six successful MCP calls and five web-search events. Blocked source retrieval remained visible and the final report stayed insufficient-evidence/low-confidence. See the validation report for exact scope, historical results and limitations; consult CI for the published revision's Linux checks.

• Data freshness: free data can be delayed or unavailable. as_of and fetched_at are retrieval times, not verified trade timestamps. A recent fetch does not establish a fresh market price.

• Evidence: SDK traces show that tools ran. They do not independently prove every claim, citation, or model-written excerpt. verification_basis is model_review.

• Backtests: holdout performance is historical. Costs vary by tool; portfolio holdout results omit fees, slippage, taxes, and currency conversion.

• Risk scenarios: historical reference distances and user-defined budgets are not execution levels or loss limits. The public tool returns no share count or order instruction; gaps, slippage and fees are not modeled by its distances.

• Scope: research jobs currently accept NSE symbols. The broader market tools also support US and BSE symbols where their providers do. No automatic trading.

Optional dashboard and lightweight workbench

Run a complete demo without API keys, a broker account, a model, or network access after installation. Load clearly labelled synthetic prices or your own daily OHLCV CSV, inspect indicators, backtest an SMA strategy with next-open fills and modeled costs, and save the results in SQLite. Optional Yahoo downloads require network access; provider failures are shown explicitly.

Run the optional dashboard

Use Python 3.12:

git clone https://github.com/paarths-collab/quant-brain-mcp.git
cd quant-brain-mcp
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements_demo.txt
python -m streamlit run dashboard.py --server.address 127.0.0.1

Open http://localhost:8501. On Windows, activate with .venv\Scripts\Activate.ps1 instead. The default sample is synthetic, not a market-price claim. The app also accepts standard and supported NSE CSV formats.

For a terminal demo:

python workbench_cli.py demo --output-dir .quant-brain/demo

For a local MCP client, launch python workbench_mcp.py as a stdio server. It exposes demo_backtest, backtest_csv, and describe_data_sources using the same calculation engine. See the five-minute demo and client setup and free data sources and limitations.

The workbench is a single-user research tool. Its backtests are historical simulations, not evidence of future profitability; it does not submit orders.

Documentation

• Proposed global market research roadmap

• Architecture, workflow, job lifecycle, and security boundaries

• Evaluation metrics and public benchmark design

• Agents, exact tool catalog, and proposed permissions

• Research runtime, authentication, and Claude connection

• Tool reference and example prompts

• Price alerts

• Deployment and operations

• MCP-only deployment: local clients, Linux supervision and Render

• VPS topology, credentials, persistence, and acceptance checks

• Ubuntu VPS installer and environment template

• Dependency maintenance

• Validation results and remaining limitations

License

MIT.

The local filing workflow also supports analyze_filings(documents, question=...) without manual comparison selectors: annual facts, balance-sheet snapshots, EPS, lookups and guarded arithmetic. The bounded English planner returns its explicit plan and asks for clarification on ambiguous questions. See the filing workflow for identity, vintage, availability, units and format limits; this is not arbitrary document QA or a valuation model.

Current document/question test results and comparison limits: filing-question validation.

Annual earnings review for non-financial equity research: use case, workflow and current validation.