bull-milker-mcp

A read-only MCP server exposing moomoo market data, the Bull Milker screener, and portfolio risk/exposure tools to Claude Desktop.

What it exposes

Important caveats — read before wiring up the "suggest investments" agent

• Sector grouping: get_portfolio_sector_exposure and get_sector_technical_outlook_tool group holdings by moomoo's real industry-type plates (via get_owner_plate), not GICS. Concept/thematic plates are excluded. A symbol with no industry-plate match is grouped under an explicitly-labeled "Unknown (no industry plate mapping)" bucket — never silently folded into a real sector.

• Sector technical signals are a proxy, not an index quote: get_sector_technical_outlook_tool's weighted_rsi_14 and SMA figures are a market-value-weighted average of each holding's own locally computed RSI/SMA, not a real sector-index feed — moomoo doesn't expose one through this API. Daily kline history is cached under data/kline_cache/ because moomoo's historical-kline quota takes 7 days to release per symbol; don't delete that cache casually or you'll burn quota re-fetching it.

• PE ratio: available directly from moomoo (pe_ttm_ratio on snapshots, or as a FinancialFilter in the screener). Included and working.

• Short volume / short interest: moomoo's snapshot endpoint exposes short_sell_rate and short_available_volume per symbol. These are fetched as an enrichment step after the screener runs (not filterable inside get_stock_filter itself, since it's not one of the screenable StockField options as far as the public API docs show).

• Institutional investment %: moomoo's app has an "Institutional Tracker" based on 13F filings, but as of writing this doesn't appear to be exposed through the public OpenAPI — 13F data is also inherently quarterly and reported with up to a 45-day lag, so even where available it's a lagging indicator, not real-time. indicators.py has a stubbed get_institutional_ownership() that raises NotImplementedError with a clear TODO — plug in a third-party data provider there (e.g. a paid fundamentals API) if you want this metric. Don't let the agent silently treat a missing/stubbed value as "0% institutional ownership" — the tool returns None explicitly so that distinction is visible upstream.

Setup

./setup.sh

Creates the venv, installs dependencies, copies .env.example to .env if missing, and prints the exact mcpServers block to paste into Claude Desktop's config. Safe to re-run — skips steps already done. Edit .env afterward to fill in your values (e.g. MOOMOO_SECURITY_FIRM).

Manual equivalent, if you'd rather not run the script:

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env           # fill in values

Requires moomoo OpenD running and logged in (see the main Bull Milker project's opend/README.md if you have it, or https://openapi.moomoo.com/moomoo-api-doc/en/intro/). The server now checks OpenD is reachable at startup and exits with a clear message if not, rather than failing opaquely on the first tool call.

Developing in VS Code

• Open this folder in VS Code.

• .vscode/launch.json is set up to run src/bull_milker_mcp/server.py directly under the debugger — set breakpoints in any tool function and step through a call.

• For a protocol-level test without any client, use the MCP Inspector:

  npx @modelcontextprotocol/inspector python -m bull_milker_mcp.server

• Run python -m bull_milker_mcp.screener for a quick manual smoke test of the screener logic alone, without going through MCP at all.

Wiring into Claude Desktop

Copy the relevant block from claude_desktop_config.example.json into your Claude Desktop MCP config, updating the cwd path. Restart Claude Desktop, then confirm the tools show up (Claude Desktop's MCP tool picker, or just ask "what tools do you have from bull-milker-mcp?").

Shutting down

./stop.sh

Stops the bull_milker_mcp server process and moomoo OpenD, so neither keeps running (or holding a live account connection) between sessions. Quit Claude Desktop first — it respawns the MCP server on demand, so killing it while Claude Desktop is still open just makes tool calls fail until the next call or a Desktop restart.

Suggested build/test order

1. check_health — confirm the OpenD round trip works at all.

2. get_market_snapshot — one real symbol, verify data shape.

3. get_account_positions — paper account.

4. run_bull_milker_screener — verify against the existing Bull Milker project's results.

5. get_portfolio_sector_exposure — test with a small known portfolio, check the math by hand.

6. run_bull_milker_extended_screener — add PE + short interest enrichment.

7. get_sector_technical_outlook_tool — first call will be slow (fetches ~380 days of daily klines per holding); re-run it and confirm the second call is fast, using the cache instead of re-fetching.

8. Wire into Claude Desktop, test each tool interactively in chat.

9. Only then: build the standing prompt and set up a Cowork scheduled task.

Safety

See SAFETY.md for the full threat model and user stories. In short: this server is read-only by design and by enforcement — guardrails.py checks for trade-execution symbols at startup, and tests/test_no_trading_capability.py fails the build if any creep in. Every tool call is logged to data/audit_log.jsonl (see audit.py).

Before adding any new tool, ask: does this need to place, modify, or cancel an order? If yes, stop and read SAFETY.md US-2 first.

Run the safety test any time: pytest tests/test_no_trading_capability.py -v

MCP SDK version note

This project targets mcp v2 (MCPServer, not the older FastMCP class — the official SDK renamed it in its July 2026 v2 release; v1 is now maintenance-only). If you're following older MCP tutorials that show from mcp.server.fastmcp import FastMCP, that's the v1 API — this repo uses from mcp.server import MCPServer instead. If your installed mcp resolves to <2.0, either upgrade (pip install "mcp[cli]>=2.0") or pin your own project to mcp>=1.28,<2 and revert this file's import — don't mix the two.

Tax reporting (live account)

get_quarterly_tax_summary computes realized capital gains/losses by quarter (Q126 format) using FIFO cost-basis matching against your LIVE account's deal history — genuinely different from get_quarterly_transaction_summary, which just counts trades on whichever account (paper by default) and does no cost-basis matching at all.

This is gated behind TAX_AUDIT_ENABLE_LIVE=true in .env — it's off by default and raises a clear PermissionError if you call it without enabling it first. See SAFETY.md US-8/US-9/US-10 before turning this on.

Not tax advice. FIFO cost basis, no wash-sale handling, no corporate actions, no dividends. Reconcile against your broker's 1099-B and talk to an actual tax professional before filing anything.