Content
# Stock Analysis MCP Server
[](tests/)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](https://github.com/ranaroussi/yfinance)
[](LICENSE)
An MCP server that gives AI agents (Claude Code, Codex, etc.) single-stock analysis capabilities.
Informational only — not financial advice.
## Philosophy
**One command, complete picture.** Just say "Analyze AAPL" and get a comprehensive,
human-readable report (section summaries, analyst coverage, ownership, short interest,
governance, and company context) in a consistent JSON schema.
## Architecture
Read left to right: request -> orchestration -> parallel data fetch -> synthesized response.
### Quick Flow
```mermaid
flowchart LR
C["AI Agent"] --> A["analyze"]
A --> O["Orchestrator"]
O --> T["Core Tools"]
T --> D["Data Client + Cache"]
D --> Y["yfinance"]
O --> R["Response JSON"]
```
### Detailed Flow
```mermaid
flowchart LR
classDef client fill:#EAF3FF,stroke:#2F6DB3,color:#12345B,stroke-width:1px;
classDef entry fill:#E9FFF4,stroke:#2E9B64,color:#0E4F32,stroke-width:1px;
classDef engine fill:#FFF7E8,stroke:#C58C2A,color:#5B3A00,stroke-width:1px;
classDef data fill:#F3EEFF,stroke:#6E4EC9,color:#2F1F63,stroke-width:1px;
classDef output fill:#FFEDEF,stroke:#C3445A,color:#5E1E2A,stroke-width:1px;
subgraph L1["Client"]
C["AI Agent<br/>Claude or Codex"]
end
subgraph L2["MCP Layer"]
S["MCP Server"]
A["analyze<br/>primary tool"]
OT["other tools<br/>compare, detect_changes<br/>get_ownership, get_options_signals"]
end
subgraph L3["Analysis Engine"]
O["Orchestrator"]
M["Modules<br/>scoring, actions, context"]
end
subgraph L4["Core Data Layer"]
T["Core tools<br/>technicals, fundamentals<br/>risk, events, news"]
D["Data client + cache"]
Y["yfinance"]
end
R["Response JSON"]
C -->|"Analyze NVDA"| S
S --> A
S --> OT
A --> O
O -->|"parallel calls"| T
OT --> T
T --> D --> Y
O --> M --> R
class C client
class S,A,OT entry
class O,M engine
class T,D,Y data
class R output
```
Color legend: `blue=client`, `green=entry`, `orange=engine`, `purple=data`, `red=output`.
Node map: `S=src/stock_mcp/server.py`, `O=src/stock_mcp/tools/analyze/orchestrator.py`, `D=src/stock_mcp/data/`.
Output shape details are documented in `Usage -> Full Analysis (Recommended)`.
### Request Lifecycle
```mermaid
sequenceDiagram
participant U as AI Agent
participant M as MCP Server
participant A as analyze
participant O as Orchestrator
participant T as Core Tools
participant D as Data Client
participant Y as yfinance
U->>M: "Analyze NVDA"
M->>A: call analyze
A->>O: start orchestration
par parallel fetch
O->>T: technicals/fundamentals/risk/events/news
end
T->>D: fetch data
D->>Y: request market data
Y-->>D: raw data
D-->>T: normalized data
T-->>O: tool outputs
O-->>M: unified response JSON
M-->>U: analysis result
```
## Quick Start
### Prerequisites
```bash
# Clone the repository
git clone https://github.com/nickzren/stock-analysis-mcp.git
cd stock-analysis-mcp
# Install dependencies
uv pip install -e .
```
### Claude Code (VS Code)
Ask Claude Code to add the server:
> "Add the stock-analysis MCP server from this directory"
Or run manually:
```bash
claude mcp add stock-analysis -- uv --directory /path/to/stock-analysis-mcp run stock-mcp
```
### Codex (VS Code)
Ask Codex to add the server:
> "Add the stock-analysis MCP server from this directory"
Or run manually:
```bash
codex mcp add stock-analysis -- uv --directory /path/to/stock-analysis-mcp run stock-mcp
```
## Usage
### Full Analysis (Recommended)
The primary way to use this server—just say:
```
"Analyze NVDA"
```
This returns a comprehensive JSON report covering:
- **Executive summary** — materiality-first narrative (leads with what matters most)
- **Section summaries** — 1–2 sentence takeaways per major section
- **Verdict** — score, tilt (bullish/neutral/bearish), confidence, horizon fit
- **Policy action** — mid/long-term decision framing with position sizing ranges (informational)
- **Action zones** — ATR-based price levels (accumulate/reduce/stop)
- **Dip assessment** — oversold metrics, support levels, bounce potential, entry timing
- **Decision context** — what would change the verdict (bullish_if/bearish_if)
- **Analyst coverage** — consensus rating + targets
- **Ownership & short interest** — insiders/institutions/float, days-to-cover
- **Governance** — audit/board/comp/rights risk scores
- **Company profile** — description, industry, employees, website
- Technical signals, fundamental metrics, risk regime, news sentiment, events
The output follows a consistent schema, making it easy to compare multiple stocks or track changes over time.
For invalid/delisted symbols, `analyze` returns a top-level error (`error=true`) with diagnostics in `data_quality.tool_failures`.
## Available Tools
### Primary
| Tool | Description |
|------|-------------|
| `analyze` | Comprehensive single-stock analysis with human-readable summaries |
### Comparative Analysis
| Tool | Description |
|------|-------------|
| `compare` | Side-by-side comparison for 2-5 symbols with rankings |
| `detect_changes` | Diff current analysis vs prior snapshot (material changes) |
### Market Data & Signals
| Tool | Description |
|------|-------------|
| `search_symbol` | Search for stock symbols by company name or ticker |
| `get_stock_summary` | Basic stock info (name, sector, price, market cap) |
| `get_price_history` | Historical price data with summary and resource URI |
| `get_technicals` | Technical indicators (SMA, EMA, RSI, MACD, Bollinger, Fibonacci, OBV) |
| `get_fundamentals` | Financial metrics, valuation history, analyst estimates, dividends |
| `get_events` | Earnings dates, dividends, splits |
| `get_news` | Recent news headlines and earnings surprise data |
| `get_ownership` | Insider transactions and institutional ownership trends |
| `get_options_signals` | Options-derived signals (IV, put/call, unusual activity) |
### Portfolio & Utilities
| Tool | Description |
|------|-------------|
| `analyze_my_position` | Hold/sell analysis for existing positions |
| `analyze_portfolio` | Concentration, sector exposure, correlation |
| `check_data_quality` | Verify data availability for symbols |
## Development
```bash
# Install dev dependencies
uv pip install -e ".[dev]"
# Run tests
uv run python -m pytest tests/ -v
# Linting
ruff check src/ tests/
```
## Disclaimer
This tool is for **informational purposes only**. It is not financial advice. Always do your own research and consult a qualified financial advisor before making investment decisions. The authors are not responsible for any financial losses incurred from using this tool.
