Stock Advisor
A FastMCP server that provides stock research, technical analysis, fundamental analysis, and scoring — all exposed as MCP tools, resources, and prompts for AI agents.
Features
- Real-time quotes – Fetch near-real-time stock prices via Finnhub with an automatic yfinance fallback.
- Price history – Retrieve OHLCV history for any ticker with configurable periods and intervals.
- Price & market-cap classification – Classify a stock by share-price band and market-cap band.
- Technical indicators – Compute RSI, MACD, moving averages (SMA 50/200), golden/death cross detection, Bollinger Bands, volume ratio, and volatility.
- Fundamental analysis – Collect trailing & forward P/E, EPS, dividend yield, debt-to-equity, ROE, revenue growth, profit margin, beta, and sector context.
- Scoring engine – Combine technical and fundamental inputs into a transparent 0–100 score with a Strong Buy / Buy / Hold / Avoid label. Customisable technical vs. fundamental weighting.
- Multi-stock comparison – Compare several tickers side-by-side on price, valuation, RSI, and overall score.
- Watchlist resource – Exposes a simple, persisted watchlist for the current session.
- Agent prompts – Built-in prompts (
analyze_stock,compare_portfolio) that guide AI agents through the analysis workflow.
Architecture
stock-advisor/
├── server.py # Entry point (PATH setup + main call)
├── pyproject.toml # Project metadata & dependencies
├── requirements.txt # Pinned dependencies
├── Dockerfile # Docker image
├── .env.example # Environment template
├── README.md
├── src/
│ └── stock_advisor/
│ ├── __init__.py
│ ├── server.py # FastMCP server: tools, resources, prompts, transport config
│ ├── data_source.py # Finnhub (primary) + yfinance (fallback) data fetching
│ ├── indicators.py # Technical indicator computations (RSI, MACD, SMA, Bollinger, volatility)
│ ├── models.py # Pydantic models for all tool inputs & outputs
│ ├── scoring.py # Scoring engine: combines technical & fundamental signals
│ └── utils.py # Ticker normalisation, period/interval validation
└── tests/
└── test_core.py # Pytest suite (150+ lines of test coverage)
Quick Start
Prerequisites
- Python 3.11+
- A Finnhub API key (free tier available)
Installation
# Clone the repository
git clone <repo-url>
cd stock-advisor
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Configure your Finnhub API key
cp .env.example .env
# Edit .env and add your Finnhub API key:
# FINNHUB_API_KEY=your_key_here
Running
Start the server over HTTP (default):
python server.py
The server listens on http://127.0.0.1:8765/mcp by default.
Using stdio transport:
MCP_TRANSPORT=stdio python server.py
Custom host / port:
HOST=0.0.0.0 PORT=8080 python server.py
MCP Tools
All tools are registered with the FastMCP server and are automatically available to any MCP-compatible AI agent (Claude, Cline, etc.).
| Tool | Description |
|---|---|
get_quote_tool(ticker) |
Fetch a near-real-time quote (Finnhub → yfinance fallback). Returns price, change %, day high/low, open, previous close. |
get_price_history_tool(ticker, period, interval) |
OHLCV history with configurable period (1d, 5d, 1mo, 6mo, 1y, 5y, max) and interval (1m, 5m, 1h, 1d, 1wk). |
classify_by_price_range_tool(ticker) |
Classify by share-price band (penny / small-cap / mid-range / high-price) and market-cap band (micro / small / mid / large). |
get_technical_indicators_tool(ticker, period) |
RSI, MACD (line + signal + histogram), SMA 50/200, golden/death cross, Bollinger Bands, volume ratio, annualised volatility. |
get_fundamentals_tool(ticker) |
Trailing & forward P/E, EPS, dividend yield, D/E, ROE, revenue growth YoY, profit margin, beta, sector. |
score_stock_tool(ticker, technical, fundamentals, tech_weight, fundamental_weight) |
0–100 composite score with transparent breakdown and label. Default weights: 40 % technical, 60 % fundamental. |
compare_stocks_tool(tickers) |
Side-by-side comparison of price, P/E, RSI, and score for up to several tickers. |
MCP Resources
| Resource URI | Description |
|---|---|
watchlist:// |
Exposes a simple comma-separated watchlist (e.g. AAPL,MSFT,NVDA,TSLA) for the current session. |
MCP Prompts
| Prompt | Description |
|---|---|
analyze_stock |
Guides an AI agent to call tools in the correct order: quote → technicals → fundamentals → scoring, then summarise. |
compare_portfolio |
Guides an AI agent to call compare_stocks_tool and summarise trade-offs across price, valuation, momentum, and score. |
Scoring Engine
The scoring engine produces a transparent, explainable 0–100 score:
| Score Range | Label |
|---|---|
| 80–100 | Strong Buy |
| 65–79 | Buy |
| 45–64 | Hold |
| 0–44 | Avoid |
Technical factors scored (40 % default weight):
- RSI oversold / neutral / overbought
- Price relative to SMA trend (above → bullish, below → bearish)
- Volume confirmation (ratio > 1.0)
Fundamental factors scored (60 % default weight):
- P/E ratio (sector-relative when sector is known, absolute otherwise)
- Debt-to-equity ratio (< 1.0 → healthy)
- Revenue growth (positive → good)
- Profit margin (positive → good)
Weights are fully customisable via the tech_weight and fundamental_weight parameters in score_stock_tool.
Data Sources
| Data | Primary Source | Fallback |
|---|---|---|
| Real-time quote | Finnhub API | yfinance |
| Price history | yfinance | — |
| Fundamentals | yfinance | — |
| Technical indicators | Computed in-house from yfinance history | — |
Configuration
All configuration is via environment variables:
| Variable | Default | Description |
|---|---|---|
FINNHUB_API_KEY |
— | Your Finnhub API key (required for quote tool) |
MCP_TRANSPORT |
http |
Transport protocol (http or stdio) |
HOST |
127.0.0.1 |
Bind address |
PORT |
8765 |
Listen port |
MCP_PATH |
/mcp |
HTTP path for the MCP endpoint |
SSL_CERTFILE |
— | Path to SSL certificate (enables HTTPS) |
SSL_KEYFILE |
— | Path to SSL private key (enables HTTPS) |
Docker
# Build
docker build -t stock-advisor .
# Run
docker run -e FINNHUB_API_KEY=your_key_here -p 8765:8765 stock-advisor
Development
Running tests
pytest
Code structure
src/stock_advisor/server.py— FastMCP server definition; all tools, resources, and prompts are registered here.src/stock_advisor/data_source.py— Data fetching layer (Finnhub API + yfinance).src/stock_advisor/indicators.py— Pure-function technical indicator computations.src/stock_advisor/models.py— Pydantic models for input validation and structured output.src/stock_advisor/scoring.py— Composite scoring logic with weighted technical/fundamental signals.src/stock_advisor/utils.py— Ticker normalisation and period/interval validation.
Disclaimer
All tools and outputs from Stock Advisor are for educational and informational purposes only. Nothing provided by this server constitutes financial advice. Always do your own research before making investment decisions.
