mcp-yfinance-ux

mcp-yfinance-ux

For AI agents: Market data in Bloomberg Terminal format. Not raw JSON - I give you formatted tables you can read directly. Navigate like BBG: markets() → sector('technology') → ticker('AAPL') → ticker_options('AAPL'). Smart defaults (auto-detects market hours), progressive disclosure (summary → detail).

For humans: Dense, scannable screens. Factor exposures, momentum, options positioning - all formatted like a professional terminal.

Technical: Local stdio server, powered by yfinance. All queries user-initiated (no automation - this is a research tool, not production infrastructure).

Example Output

Our differentiator: BBG Lite formatted, agent-friendly screens

MARKETS | Sun 2025-10-26 12:42 EDT

US EQUITIES                   PRICE     CHANGE       1M         1Y
S&P 500                      6791.69    +0.79%     +2.2%     +16.9%
Nasdaq                      23204.87    +1.15%     +3.2%     +25.3%
Dow                         47207.12    +1.01%     +2.1%     +12.1%
Russell 2000                 2513.47    +1.24%     +3.3%     +13.8%

SECTORS          TICKER      PRICE     CHANGE       1M         1Y
Technology       XLK          293.58    +1.23%     +5.3%     +28.3%
Financials       XLF           53.11    +0.84%     -1.4%     +15.6%
Healthcare       XLV          146.03    -0.05%     +7.8%      +0.0%
Energy           XLE           88.07    -1.01%     -4.3%      +1.4%
[... all 11 GICS sectors]

COMMODITIES                   PRICE     CHANGE       1M         1Y
Gold                         4137.80    +0.05%     +9.6%     +51.0%
Oil WTI                        61.50    +0.10%     -6.4%     -14.3%

Data as of 2025-10-26 12:42 EDT | Source: yfinance

Dense, scannable, professional. Not raw JSON - formatted for humans, AI benefits automatically.

Features

Bloomberg Terminal-style navigation screens for market data:

• markets() - Complete factor landscape (US equities, global, sectors, styles, commodities, volatility)
• sector(name) - Sector drill-down with top holdings and factor exposures
• ticker(symbol) - Individual security analysis with full factor decomposition
• Batch comparison - Side-by-side stock analysis with key factors
• Calendar integration - Earnings dates, dividend schedules
• BBG Lite formatting - Dense, scannable, professional output

Library Architecture

mcp-yfinance-ux includes a reusable library for reliable yfinance data fetching.

lib/yfinance_fetcher.py

ONE SOURCE OF TRUTH for yfinance fetching logic:

• Individual yf.Ticker().history() calls with ThreadPoolExecutor (RELIABLE)
• NOT yf.download() batch API (UNRELIABLE - timeouts, fails entire batch)

Used by:

1. MCP server - mcp_yfinance_ux/historical.py imports from lib/
2. Portfolio scripts - Can be copied to portfolio agents for reliable fetching
3. Any Python code - Pure logic, no MCP dependencies

Key functions:

• fetch_price_history(symbol, months=12) - Single symbol history
• fetch_multiple_histories(symbols, months=12) - Parallel multi-symbol fetch
• fetch_ticker_and_market(symbol, months=12) - Ticker + market data (for factor analysis)
• fetch_price_at_date(symbol, date) - Price at specific date (narrow window)

Why this pattern works:

• Individual fetches don't fail as a batch
• ThreadPoolExecutor provides parallelism without batch API
• Proven in production use (MCP server serving real users)

Documentation: See lib/README.md for usage examples and deployment workflow.

Important: Usage Limitations

This tool is designed for ad-hoc, user-initiated requests only. Not for automation.

What yfinance Is

yfinance is an unofficial web scraper, not a sanctioned Yahoo Finance API. It mimics browser requests to fetch financial data.

Implications:

• Can break at any time - Yahoo site changes can break the library entirely
• No official rate limits - Because it's not an official API
• Prone to blocking - Automated polling or high-volume requests trigger Yahoo's anti-scraping measures (429 errors, IP bans)
• No guarantees - Yahoo tightened restrictions significantly around early 2024

Safe Usage (What This Tool Does)

✅ Appropriate use cases:

• Ad-hoc market checks and analysis
• One-off stock research
• Manual thesis development
• Occasional queries for specific data

All queries are user-initiated and interactive.

Unsafe Usage (Don't Do This)

❌ Never use this for:

• Cron jobs or scheduled updates
• Automated monitoring loops
• Background processes polling for data
• Production infrastructure
• Real-time portfolio tracking

If you need automation or production-grade data, use official APIs instead (Alpha Vantage, Polygon.io, IEX Cloud, etc.)

Bottom Line

This MCP server is a research tool for occasional queries, not production infrastructure. Perfect for PMF testing and ad-hoc analysis. Not suitable for automation or continuous monitoring.

Installation

1. Clone and install dependencies

git clone https://github.com/bxxd/idio-mcp-yfinance-ux.git
cd idio-mcp-yfinance-ux
poetry install

2. Configure MCP Client

Note: This is a local stdio MCP server. It runs on your machine and connects to MCP clients via standard I/O (not HTTP/network). All data stays local.

Method 1: Using make -C (recommended)

From your project directory:

claude mcp add idio-yf make -C /absolute/path/to/mcp-yfinance-ux serve

Or manually add to ~/.claude.json under your project's mcpServers:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "idio-yf": {
          "type": "stdio",
          "command": "make",
          "args": ["-C", "/absolute/path/to/mcp-yfinance-ux", "serve"],
          "env": {}
        }
      }
    }
  }
}

Why this approach?

• Single source of truth (Makefile defines the server command)
• No need to remember poetry/python invocation details
• Self-documenting (Makefile is version controlled)
• Works from any directory (make -C handles working directory)

Method 2: Direct command (alternative)

If you prefer not to use make:

claude mcp add idio-yf poetry run python -m mcp_yfinance_ux.server --cwd /path/to/mcp-yfinance-ux

Or manually:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "idio-yf": {
          "type": "stdio",
          "command": "poetry",
          "args": ["run", "python", "-m", "mcp_yfinance_ux.server"],
          "cwd": "/absolute/path/to/mcp-yfinance-ux",
          "env": {}
        }
      }
    }
  }
}

Note: For claude CLI users, MCP servers are configured per-project in ~/.claude.json. Other MCP clients may have different configuration methods.

Method 3: SSE/HTTP Server (for web-based deployments)

For web interfaces or when you need a persistent HTTP server:

# Start HTTP server (runs in background on port 5001)
make server

# Or specify custom port
PORT=8080 make server

# Check logs
make logs

Configure Claude Code to use SSE transport:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "yfinance-ux": {
          "type": "sse",
          "url": "http://127.0.0.1:5001/sse"
        }
      }
    }
  }
}

When to use SSE:

• Web-based Claude Code deployments (e.g., browser terminals)
• Multiple clients sharing one server instance
• Debugging without restarting Claude Code

When to use stdio:

• Local CLI usage (standard approach)
• Single-user development environment

3. Restart MCP Client

After configuration, restart your MCP client to load the server.

How it works:

• stdio mode: MCP client launches server as subprocess, communicates via stdin/stdout
• SSE mode: MCP client connects to persistent HTTP server via Server-Sent Events

Usage

Navigation hierarchy like Bloomberg Terminal:

markets() → sector('technology') → ticker('AAPL')

markets() - Market Overview

Complete factor landscape with no parameters:

mcp__idio_yf__markets()

Shows:

• US EQUITIES - S&P 500, Nasdaq, Dow, Russell 2000 (with Beta, 1M/1Y momentum)
• GLOBAL - Europe (STOXX 50), Asia (Nikkei), China (Shanghai)
• SECTORS - All 11 GICS sectors (XLK, XLF, XLV, etc.) with Beta and momentum
• STYLES - Momentum (MTUM), Value (VTV), Growth (VUG), Quality (QUAL), Size (IWM)
• COMMODITIES - Gold, Oil, Natural Gas (with Beta and momentum)
• VOLATILITY & RATES - VIX, 10Y Treasury

Auto-detects market hours (shows futures after hours, indices during market).

sector(name) - Sector Drill-Down

Detailed sector analysis with top holdings:

mcp__idio_yf__sector(name='technology')

Shows:

• Sector ETF price and momentum (1M, 1Y)
• Beta to SPX, idiosyncratic volatility
• Top 10 holdings with symbol, name, weight, and individual betas

Available sectors: technology, financials, healthcare, energy, consumer_disc, consumer_stpl, industrials, utilities, materials, real_estate, communication

ticker(symbol) - Individual Security Analysis

Complete factor decomposition for stocks:

mcp__idio_yf__ticker(symbol='AAPL')

Shows:

• Factor Exposures - Beta (SPX), idiosyncratic volatility, total volatility
• Valuation - P/E ratio, forward P/E, dividend yield
• Calendar - Next earnings date with estimates, ex-dividend date, payment date
• Momentum & Technicals - 1M/1Y returns, RSI (14D), 50/200-day moving averages
• 52-Week Range - Visual bar showing current position

Batch Comparison

Side-by-side stock comparison:

mcp__idio_yf__ticker(symbol=['TSLA', 'F', 'GM'])

Table format showing: Symbol, Name, Price, Change%, Beta, Idio Vol, 1Y Momentum, P/E, Dividend Yield, RSI

Output Format

BBG Lite style - Dense, scannable, professional formatting like Bloomberg Terminal.

Example ticker() output:

AAPL US EQUITY                   LAST PRICE  262.24 +9.95  +3.94%
Apple Inc.                               MKT CAP  3891.7B    VOLUME  90.1M

FACTOR EXPOSURES
Beta (SPX)       1.09
Idio Vol         21.7%
Total Vol        32.8%

VALUATION
P/E Ratio         39.85
Forward P/E       31.56
Dividend Yield    0.40%

CALENDAR
Earnings         Oct 30, 2025  (Est $1.77 EPS)
Ex-Dividend      Aug 11, 2025
Div Payment      Aug 14, 2025

MOMENTUM & TECHNICALS
1-Month            +6.8%
1-Year            +11.4%
50-Day MA         241.73
200-Day MA        222.14
RSI (14D)         59.5

52-WEEK RANGE
High              264.38
Low               169.21
Current           262.24  [===================░]  98% of range

Example batch comparison:

TICKER COMPARISON 2025-10-21 08:42 EDT

SYMBOL   NAME                                PRICE     CHG%   BETA   IDIO    MOM1Y      P/E   DIV%    RSI
---------------------------------------------------------------------------------------------------------
AAPL     Apple Inc.                         262.24   +3.94%   1.09  21.7%   +11.4%    39.85  0.40%   59.5
MSFT     Microsoft Corporation              516.79   +0.63%   1.02  17.0%   +24.3%    37.89  0.70%   48.8
GOOGL    Alphabet Inc.                      256.55   +1.28%   1.00  25.5%   +57.1%    27.32  0.33%   66.1

Clean, readable, immediately useful.

Development

Quick Start

Using Makefile (recommended):

make all        # Run lint + test (ALWAYS before committing)
make test       # Run tests
make lint       # Run type checking + linting
make lint-fix   # Auto-fix linting issues
make serve      # Run MCP server (stdio mode)
make help       # Show all commands

Manual testing (no MCP required):

# Test screens via CLI (no MCP restart needed)
./cli markets
./cli sector technology
./cli ticker AAPL
./cli ticker TSLA F GM    # Batch comparison

Documentation

• DEVELOPER.md - Design philosophy, engineering principles, development process
• CLAUDE.md - Additional context and development notes

Design Principles

• Separation of Concerns - Business logic has zero MCP dependencies
• Single Source of Truth - One true path for every piece of data/logic
• Human-Readable Output - Format for humans, not machines
• Keep It Simple - Match manual testing exactly, no overengineering

License

MIT