# 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

| Tool | What it does |
|---|---|
| `check_health` | Confirms OpenD is reachable |
| `get_account_positions` | Current paper/live positions |
| `get_market_snapshot` | Live price/volume/change for given codes |
| `run_bull_milker_screener` | Screener: turnover, volume, and % change filters, configurable via `.env` |
| `run_bull_milker_extended_screener` | Bull Milker + PE ratio and short-interest enrichment (see caveats below) |
| `get_portfolio_sector_exposure` | Deterministic concentration calc across your current positions, grouped by real moomoo industry-plate sectors |
| `get_sector_technical_outlook_tool` | RSI/SMA technical signals aggregated per sector, holdings-weighted (see below) |
| `get_quarterly_transaction_summary_tool` | Trade counts by quarter (Q126 format), no cost-basis matching |
| `get_quarterly_tax_summary_tool` | Realized gain/loss by quarter, FIFO cost basis, LIVE account only (opt-in) |

## 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

```bash
./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:

```bash
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:
  ```bash
  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

```bash
./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.