portfolio-signals-mcp
# Portfolio Signals MCP
[](https://pypi.org/project/portfolio-signals-mcp/)
[](https://pypi.org/project/portfolio-signals-mcp/)
[](LICENSE)
An MCP server that gives any AI coding agent (Claude Code, Cursor, Claude Desktop, etc.) real-time stock quotes and **computed** technical-analysis signals — RSI, MACD crossovers, golden/death crosses, and whole-portfolio weekly digests. Indicators are calculated in code, not by the LLM, so the numbers are right.
Data source: Yahoo Finance via [yfinance](https://github.com/ranaroussi/yfinance) — free, no API key required.
mcp-name: io.github.KhizarShabir1/portfolio-signals
## Tools
| Tool | What it does |
|---|---|
| `get_quote(ticker)` | Price, day change, volume, 52-week range |
| `get_technical_signals(ticker)` | RSI(14) with overbought/oversold zone, MACD(12,26,9) vs signal line, SMA 50/200 golden/death cross |
| `compare_tickers(tickers, period)` | Ranked total returns over 1mo–5y |
| `weekly_digest(tickers)` | Whole-portfolio report: 1w/1mo returns, RSI, MACD position, tickers outside RSI 30–70 |
**Design principle:** tools return measurements and standard threshold classifications (RSI 70/30 zones, golden/death cross, MACD vs signal line) — never directional opinions or narrative summaries. Interpretation is the agent's job; determinism is the server's.
**Batch tools degrade per ticker:** if one symbol fails, `compare_tickers` and `weekly_digest` still return the rest, and the failed entry carries `error` and `error_type`. `TickerNotFoundError` means a bad symbol (don't retry); other types, such as `ConnectionError`, are transient (retry).
## Quick start
No install needed if you have [uv](https://docs.astral.sh/uv/):
```bash
uvx portfolio-signals-mcp
```
### Claude Code
```bash
claude mcp add portfolio-signals -- uvx portfolio-signals-mcp
```
Then ask Claude things like:
- *"What's the RSI and MACD on NVDA right now?"*
- *"Compare AAPL, MSFT and VOO over 6 months."*
- *"Give me a weekly digest for my portfolio: AAPL, NVDA, VOO, TSLA."*
### Cursor
Settings → Tools & MCP → Add a Custom MCP Server:
```json
{
"mcpServers": {
"portfolio-signals": {
"command": "uvx",
"args": ["portfolio-signals-mcp"]
}
}
}
```
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"portfolio-signals": {
"command": "uvx",
"args": ["portfolio-signals-mcp"]
}
}
}
```
## From source
```bash
git clone https://github.com/KhizarShabir1/portfolio-signals-mcp
cd portfolio-signals-mcp
pip install -e .
portfolio-signals-mcp # stdio
portfolio-signals-mcp --http # streamable HTTP on :8000 (PORT env to change)
```
## Tests
```bash
pip install -e ".[test]"
pytest -m "not network" # offline: indicator math, 52-week range, error handling, tool schema
pytest tests/test_mcp_e2e.py -v # end to end: starts the real server over stdio and calls every tool through the protocol (needs internet)
```
## Disclaimer
Informational only — not financial advice. Market data comes from Yahoo Finance and is subject to Yahoo's terms of use.
## License
MIT © [Khizar Shabir](https://github.com/KhizarShabir1)
TDQS
Scored across 4 tools
The four tools have mostly distinct purposes: quote retrieval, technical indicator computation, multi-ticker comparison, and a composite weekly digest. The only mild overlap is between compare_tickers and weekly_digest, since the digest includes returns and indicator readings, but the digest's recurring-report framing makes the boundary reasonably clear.
Names use snake_case throughout, with three following a clear verb_noun pattern: get_quote, get_technical_signals, and compare_tickers. weekly_digest is a noun phrase rather than verb-led, which is a minor but understandable deviation.
Four tools is well-scoped for a portfolio-signals server: one quote tool, one technical-signals tool, one comparison tool, and one digest tool. Each has a clear role and the set avoids unnecessary surface area.
The surface covers the core workflow of retrieving quotes, computing technical signals, comparing returns, and producing a weekly portfolio digest. Minor gaps remain, such as standalone historical price retrieval or richer risk/portfolio analytics, but the essential signals domain is covered.