Language
ValueScope
A standardized DCF valuation engine your AI can call — deterministic, reproducible, and built for A-shares / HK / US / JP.
What is ValueScope?
ValueScope is a standardized Damodaran FCFF DCF engine — 10-year explicit forecast, terminal value, WACC, sensitivity analysis, and reverse DCF in a fixed, reproducible framework.
Ask an LLM to "value this stock" and every conversation may use a different data source, accounting convention, and model — you can't tell whether a changed valuation means the fundamentals moved or the AI just felt different this time. ValueScope solves that with a clean division of labor:
- Your AI does the judgment — searches earnings guidance, analyst consensus, and industry benchmarks, then reasons about each assumption.
- The engine does the data and the math — A-share deducted-NI convention, non-operating-item EBIT adjustment, 10-year FCFF discounting, sensitivity, reverse DCF. Same inputs always yield the same output.
Your AI brings the intelligence; ValueScope brings the framework and the discipline. The engine itself never calls an LLM.
Supported Markets: 🇨🇳 A-shares 🇭🇰 Hong Kong 🇺🇸 US 🇯🇵 Japan
Three ways to use it: the MCP server (call it from your own AI), the web app (manual operator console), and the terminal CLI.
MCP Server
The MCP (Model Context Protocol) server lets any MCP-capable AI client — Claude, ChatGPT, Cherry Studio, Dify, and others — call the same deterministic DCF engine the web app uses. This is the recommended way to use ValueScope.
Endpoint: https://mcp.valuescope.app/mcp
Connect in two minutes
Claude Code (terminal and desktop app share one config):
claude mcp add valuescope --transport http https://mcp.valuescope.app/mcp
Claude web / mobile app: Settings → Connectors → add a custom connector, paste https://mcp.valuescope.app/mcp.
Cherry Studio and other desktop clients: add an MCP server of type HTTP with the same URL.
Then just ask in natural language: "Value Kweichow Moutai with a DCF" — no commands to learn.
How it works — one tool, two phases
get_score (four-dimension check-up) and get_relative_valuation (current multiples plus
historical percentiles) answer "how is this company, and is it cheap against its own history"
in a single call.
run_dcf answers "what is it worth", mirroring an equity analyst's workflow with the calling
model playing the analyst:
- Material — call
run_dcf(ticker) with no assumptions. Returns the historical financials, each parameter's historical range, the engine-computed WACC and tax rate, and an analyst guide telling the model how to evaluate every assumption. No valuation is returned — a number at this point would only anchor the reasoning that follows.
- Final — the model searches the web for guidance and consensus, reasons about each parameter, then calls
run_dcf(ticker, <assumptions>) for the final valuation: intrinsic value, value bridge, forecast table, sensitivity matrix, and reverse DCF (what the market price implies).
A dcf MCP prompt is also exposed, surfacing a one-command workflow (material → search → reason → three scenarios) in clients that support MCP prompts.
Ticker format: A-shares 600519.SS / 000333.SZ, HK 0700.HK, US AAPL, JP 7203.T.
FMP key for US / JP
A-shares and HK need no key. US / JP data comes from FMP (see Data Sources). US/JP tickers get a small daily free trial served by the server; beyond that, provide your own key one of two ways:
Configure once (recommended) — pass it as a request header so every conversation uses it automatically. If you already added the server without a key, remove and re-add it:
claude mcp remove valuescope
claude mcp add valuescope --transport http https://mcp.valuescope.app/mcp --header "X-FMP-Key: YOUR_KEY"
claude.ai custom connector (web / mobile app) — claude.ai does not accept the X-FMP-Key header name there. Add a header named Authorization with the value Bearer YOUR_KEY instead, or put the key in the connector URL: https://mcp.valuescope.app/mcp?fmp_key=YOUR_KEY.
Per-conversation — just say "my FMP key is …" in the chat; the model passes it on each call (only valid for that conversation).
Self-hosting the MCP server
The server is mounted on the FastAPI backend at /mcp (streamable HTTP). Run the backend (see Installation) and it's available at http://localhost:8000/mcp. Set FMP_API_KEY in the environment to enable the US/JP trial; tune MCP_DAILY_LIMIT and MCP_US_TRIAL_DAILY_LIMIT for rate limits.
Web App
Try it at valuescope.app — no installation required.
The web app is the manual operator console: dial in DCF parameters by hand, watch the valuation update live, read sensitivity tables, and eyeball relative-valuation percentiles and multi-factor scores. If you like driving the assumptions yourself, it's a solid DCF calculator.
Features
- DCF Valuation — Damodaran FCFF framework with interactive parameter controls, 10-year forecast table, dual sensitivity analysis (Growth×Margin, WACC), and bridge-to-value breakdown.
- Relative Valuation — Current multiples (PE, PB, PS, EV/EBITDA) vs historical percentiles across 3/5/10-year windows.
- 4-Dimension Scoring — Valuation, Quality, Growth, and Momentum in a radar chart with transparent sub-factor breakdown.
- Financial Overview — Key drivers (revenue growth, EBIT margin, ROIC, FCF), balance sheet highlights, and historical financial table.
- Bilingual UI — English and Chinese with one-click toggle.
Terminal CLI
For local use with your own AI CLI subscription. Requires Python 3.8+.
- AI Copilot — local AI engine (Claude / Gemini / Qwen) suggests parameters; you review and adjust interactively.
- Custom Valuation — full manual control with
--manual. No AI or API key required.
- Auto Mode — fully automated with
--auto: AI → accept → export Excel.
- Excel Export — formatted
.xlsx with valuation results, historical data, and AI reasoning.
| Engine | Install | Notes |
|---|
| Claude | npm install -g @anthropic-ai/claude-code | Default if available. |
| Gemini | npm install -g @google/gemini-cli | Free with a Google account. |
| Qwen | npm install -g @anthropic-ai/qwen-code | Free with a qwen.ai account. |
Auto-detects installed engines (priority: Claude > Gemini > Qwen), or force one with --engine. If none is found, falls back to manual mode.
Data Sources & FMP API Key
| Market | Data Source | API Key |
|---|
| A-shares | akshare | Not required (free) |
| Hong Kong | yfinance (annual) / FMP (quarterly) | Annual: free; Quarterly: FMP key |
| US | FMP | FMP key required |
| Japan | FMP | FMP key required |
💡 Get an FMP API Key →
FMP (Financial Modeling Prep) provides high-quality financial data for US, HK, and JP markets. Subscribing through this link (coupon valuescope included) is discounted — and supports ValueScope's ongoing development.
Installation & Usage
Option 1: MCP Server (Recommended)
No installation — connect your AI to https://mcp.valuescope.app/mcp (see MCP Server above).
Option 2: Web App
Visit valuescope.app — no installation needed.
Option 3: Self-host (CLI + backend + MCP)
Requires Python 3.8+.
git clone https://github.com/alanhewenyu/ValueScope.git
cd ValueScope
pip install -r requirements.txt # CLI
pip install -r requirements-api.txt # backend + MCP server
Set your FMP API key (required for US/Japan):
export FMP_API_KEY='your_api_key_here'
Run the CLI:
python main.py # AI copilot (default)
python main.py --manual # Manual input
python main.py --auto # Fully automated
Or run the backend (serves the REST API and the MCP server at /mcp):
uvicorn backend.main:app --host 0.0.0.0 --port 8000
Architecture
valuescope/
├── frontend/ # Next.js (React) — web UI
├── backend/ # FastAPI — REST API + MCP server
│ └── mcp_server.py # MCP tool (run_dcf) + dcf prompt
├── modeling/ # Core valuation engine (shared by CLI, backend, MCP)
├── main.py # Terminal CLI entry point
└── Dockerfile # Backend container
The modeling/ engine is the single source of truth — the CLI, the web backend, and the MCP server all call it, so a valuation is identical no matter how you reach it.
Key Valuation Parameters
| Parameter | Description |
|---|
| Revenue Growth (Year 1) | Next year's revenue forecast. Prioritize company guidance, then analyst consensus. |
| Revenue Growth (Years 2-5) | Compound annual growth rate (CAGR) for years 2-5. |
| Target EBIT Margin | Expected EBIT margin at maturity. |
| Revenue/Invested Capital | Capital efficiency ratio for different periods. |
| WACC | Auto-calculated from risk-free rate, ERP, and beta; adjustable. |
| RONIC | Return on new invested capital in terminal period. Defaults to WACC. |
Contributing
Issues and pull requests are welcome. Contact: [email protected]
For more on company valuation, visit jianshan.co or scan to follow on WeChat:
License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
You are free to use, modify, and distribute this software, but any modified version — including use as a network service (SaaS) or a hosted MCP server — must also be open-sourced under AGPL-3.0.
© 2025-2026 Alan He
