moomoo-api-mcp 0.1.6__py3-none-any.whl

moomoo_mcp/tools/account.py

@@ -0,0 +1,296 @@
+"""Account tools for trading account information retrieval."""
+
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+
+from moomoo_mcp.server import AppContext, mcp
+
+
+@mcp.tool()
+async def get_accounts(
+    ctx: Context[ServerSession, AppContext]
+) -> list[dict]:
+    """Get list of trading accounts.
+
+    Returns list of account dictionaries with acc_id, trd_env (REAL/SIMULATE), etc.
+
+    IMPORTANT: This returns both REAL and SIMULATE accounts. To access REAL account
+    data via other tools (get_assets, get_positions, etc.), you must first call
+    unlock_trade with the trading password.
+
+    Returns:
+        List of account dictionaries containing acc_id, trd_env, and other metadata.
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    accounts = trade_service.get_accounts()
+    await ctx.info(f"Retrieved {len(accounts)} accounts")
+    return accounts
+
+
+@mcp.tool()
+async def get_account_summary(
+    ctx: Context[ServerSession, AppContext],
+    trd_env: str = "REAL",
+    acc_id: int = 0,
+) -> dict:
+    """Get complete account summary including assets and positions in one call.
+
+    This is the recommended tool for getting a full view of an account's status.
+    It combines get_assets and get_positions into a single response.
+
+    IMPORTANT FOR AI AGENTS:
+    - Default is REAL account. You MUST notify the user clearly that you are
+      accessing their REAL trading account before proceeding.
+    - For REAL accounts, you must call unlock_trade first with the trading password.
+    - If user wants SIMULATE account, they must explicitly request it.
+
+    Args:
+        trd_env: Trading environment. 'REAL' (default, requires unlock_trade first)
+            or 'SIMULATE' (no unlock needed, for testing).
+        acc_id: Account ID. Must be obtained from get_accounts().
+
+    Returns:
+        Dictionary with 'assets' (cash, market_val, etc.) and 'positions' (list of holdings).
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+
+    assets = trade_service.get_assets(trd_env=trd_env, acc_id=acc_id)
+    positions = trade_service.get_positions(trd_env=trd_env, acc_id=acc_id)
+
+    await ctx.info(f"Retrieved summary for {trd_env} account: {len(positions)} positions")
+
+    return {
+        "assets": assets,
+        "positions": positions,
+    }
+
+
+@mcp.tool()
+async def get_assets(
+    ctx: Context[ServerSession, AppContext],
+    trd_env: str = "REAL",
+    acc_id: int = 0,
+    refresh_cache: bool = False,
+    currency: str | None = None,
+) -> dict:
+    """Get account assets including cash, market value, buying power.
+
+    IMPORTANT FOR AI AGENTS:
+    - Default is REAL account. You MUST notify the user clearly that you are
+      accessing their REAL trading account before proceeding.
+    - For REAL accounts, you must call unlock_trade first with the trading password.
+    - If user wants SIMULATE account, they must explicitly request it.
+
+    Args:
+        trd_env: Trading environment. 'REAL' (default, requires unlock_trade first)
+            or 'SIMULATE' (no unlock needed, for testing).
+        acc_id: Account ID. Must be obtained from get_accounts().
+        refresh_cache: Whether to refresh the cache.
+        currency: Filter by currency (e.g., 'HKD', 'USD'). Leave None for default.
+
+    Returns:
+        Dictionary with asset information including cash, market_val, total_assets, etc.
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    assets = trade_service.get_assets(
+        trd_env=trd_env,
+        acc_id=acc_id,
+        refresh_cache=refresh_cache,
+        currency=currency,
+    )
+    await ctx.info(f"Retrieved assets for {trd_env} account")
+    return assets
+
+
+@mcp.tool()
+async def get_positions(
+    ctx: Context[ServerSession, AppContext],
+    code: str = "",
+    market: str = "",
+    pl_ratio_min: float | None = None,
+    pl_ratio_max: float | None = None,
+    trd_env: str = "REAL",
+    acc_id: int = 0,
+    refresh_cache: bool = False,
+) -> list[dict]:
+    """Get current positions.
+
+    IMPORTANT FOR AI AGENTS:
+    - Default is REAL account. You MUST notify the user clearly that you are
+      accessing their REAL trading account before proceeding.
+    - For REAL accounts, you must call unlock_trade first with the trading password.
+    - If user wants SIMULATE account, they must explicitly request it.
+
+    Args:
+        code: Filter by stock code (e.g., 'US.AAPL').
+        market: Filter by market (e.g., 'US', 'HK', 'CN', 'SG', 'JP').
+        pl_ratio_min: Minimum profit/loss ratio filter.
+        pl_ratio_max: Maximum profit/loss ratio filter.
+        trd_env: Trading environment. 'REAL' (default, requires unlock_trade first)
+            or 'SIMULATE' (no unlock needed, for testing).
+        acc_id: Account ID. Must be obtained from get_accounts().
+        refresh_cache: Whether to refresh cache.
+
+    Returns:
+        List of position dictionaries with code, qty, cost_price, market_val, pl_ratio, etc.
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    positions = trade_service.get_positions(
+        code=code,
+        market=market,
+        pl_ratio_min=pl_ratio_min,
+        pl_ratio_max=pl_ratio_max,
+        trd_env=trd_env,
+        acc_id=acc_id,
+        refresh_cache=refresh_cache,
+    )
+    await ctx.info(f"Retrieved {len(positions)} positions from {trd_env} account")
+    return positions
+
+
+@mcp.tool()
+async def get_max_tradable(
+    ctx: Context[ServerSession, AppContext],
+    order_type: str,
+    code: str,
+    price: float,
+    order_id: str = "",
+    adjust_limit: float = 0,
+    trd_env: str = "REAL",
+    acc_id: int = 0,
+) -> dict:
+    """Get maximum tradable quantity for a stock.
+
+    IMPORTANT FOR AI AGENTS:
+    - Default is REAL account. You MUST notify the user clearly that you are
+      accessing their REAL trading account before proceeding.
+    - For REAL accounts, you must call unlock_trade first with the trading password.
+    - If user wants SIMULATE account, they must explicitly request it.
+
+    Args:
+        order_type: Order type (e.g., 'NORMAL', 'LIMIT', 'MARKET').
+        code: Stock code (e.g., 'US.AAPL').
+        price: Target price for the order.
+        order_id: Optional order ID for modification scenarios.
+        adjust_limit: Adjust limit percentage.
+        trd_env: Trading environment. 'REAL' (default, requires unlock_trade first)
+            or 'SIMULATE' (no unlock needed, for testing).
+        acc_id: Account ID. Must be obtained from get_accounts().
+
+    Returns:
+        Dictionary with max_cash_buy, max_cash_and_margin_buy, max_position_sell, etc.
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    max_qty = trade_service.get_max_tradable(
+        order_type=order_type,
+        code=code,
+        price=price,
+        order_id=order_id,
+        adjust_limit=adjust_limit,
+        trd_env=trd_env,
+        acc_id=acc_id,
+    )
+    await ctx.info(f"Retrieved max tradable for {code} in {trd_env} account")
+    return max_qty
+
+
+@mcp.tool()
+async def get_margin_ratio(
+    ctx: Context[ServerSession, AppContext],
+    code_list: list[str],
+) -> list[dict]:
+    """Get margin ratio for stocks.
+
+    Args:
+        code_list: List of stock codes (e.g., ['US.AAPL', 'US.TSLA']).
+
+    Returns:
+        List of margin ratio dictionaries.
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    ratios = trade_service.get_margin_ratio(code_list=code_list)
+    await ctx.info(f"Retrieved margin ratios for {len(code_list)} stocks")
+    return ratios
+
+
+@mcp.tool()
+async def get_cash_flow(
+    ctx: Context[ServerSession, AppContext],
+    clearing_date: str = "",
+    trd_env: str = "REAL",
+    acc_id: int = 0,
+) -> list[dict]:
+    """Get account cash flow history.
+
+    IMPORTANT FOR AI AGENTS:
+    - Default is REAL account. You MUST notify the user clearly that you are
+      accessing their REAL trading account before proceeding.
+    - For REAL accounts, you must call unlock_trade first with the trading password.
+    - If user wants SIMULATE account, they must explicitly request it.
+
+    Args:
+        clearing_date: Filter by clearing date (YYYY-MM-DD format).
+        trd_env: Trading environment. 'REAL' (default, requires unlock_trade first)
+            or 'SIMULATE' (no unlock needed, for testing).
+        acc_id: Account ID. Must be obtained from get_accounts().
+
+    Returns:
+        List of cash flow record dictionaries.
+    """
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    cash_flows = trade_service.get_cash_flow(
+        clearing_date=clearing_date,
+        trd_env=trd_env,
+        acc_id=acc_id,
+    )
+    await ctx.info(f"Retrieved {len(cash_flows)} cash flow records from {trd_env} account")
+    return cash_flows
+
+
+
+@mcp.tool()
+async def unlock_trade(
+    ctx: Context[ServerSession, AppContext],
+    password: str | None = None,
+    password_md5: str | None = None,
+) -> dict:
+    """Unlock trade to access REAL account data.
+
+    IMPORTANT: You MUST call this tool before accessing REAL account data via other
+    tools (get_assets, get_positions, get_max_tradable, get_cash_flow with trd_env='REAL').
+
+    This is NOT required for SIMULATE accounts - they work without unlocking.
+
+    Workflow for accessing REAL account data:
+    1. First call unlock_trade(). It will try to use environment variables first.
+       - Checks MOOMOO_TRADE_PASSWORD (plain text)
+       - Checks MOOMOO_TRADE_PASSWORD_MD5 (md5 hash)
+    2. If that fails or if you want to provide credentials explicitly, call
+       unlock_trade(password='your_trading_password').
+    3. Then call other tools with trd_env='REAL'.
+
+    Args:
+        password: Plain text trade password (the password you set in Moomoo app).
+            If not provided, will look for MOOMOO_TRADE_PASSWORD env var.
+        password_md5: MD5 hash of trade password (alternative to password).
+            If not provided, will look for MOOMOO_TRADE_PASSWORD_MD5 env var.
+            Provide either password or password_md5, not both.
+
+    Returns:
+        Success status dictionary with {'status': 'unlocked'}.
+
+    Note:
+        The unlock state is maintained for the session. You only need to call this
+        once per session to access REAL account data.
+    """
+    import os
+
+    # If no args provided, try env vars
+    if not password and not password_md5:
+        password = os.environ.get("MOOMOO_TRADE_PASSWORD")
+        password_md5 = os.environ.get("MOOMOO_TRADE_PASSWORD_MD5")
+
+    trade_service = ctx.request_context.lifespan_context.trade_service
+    trade_service.unlock_trade(password=password, password_md5=password_md5)
+    await ctx.info("Trade unlocked successfully - REAL account data is now accessible")
+    return {"status": "unlocked", "message": "You can now access REAL account data by setting trd_env='REAL' in other tools"}

moomoo_mcp/tools/market_data.py

@@ -0,0 +1,212 @@
+
+"""Market data tools for retrieving stock quotes, K-lines, snapshots, and order book."""
+
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+
+from moomoo_mcp.server import AppContext, mcp
+
+
+@mcp.tool()
+async def get_stock_quote(
+    ctx: Context[ServerSession, AppContext],
+    codes: list[str],
+) -> list[dict]:
+    """Get real-time stock quotes for specified codes.
+
+    Returns current price, open, high, low, volume, and other quote data.
+    Automatically subscribes to the stocks before fetching quotes.
+
+    Args:
+        codes: List of stock codes (e.g., ['US.AAPL', 'HK.00700']).
+
+    Returns:
+        List of quote dictionaries containing:
+        - code: Stock code
+        - last_price: Latest price
+        - open_price: Open price
+        - high_price: High price
+        - low_price: Low price
+        - prev_close_price: Previous close
+        - volume: Trading volume
+        - turnover: Turnover amount
+        - And other quote fields
+    """
+    market_data_service = ctx.request_context.lifespan_context.market_data_service
+    quotes = market_data_service.get_stock_quote(codes)
+    await ctx.info(f"Retrieved quotes for {len(codes)} stocks")
+    return quotes
+
+
+@mcp.tool()
+async def get_historical_klines(
+    ctx: Context[ServerSession, AppContext],
+    code: str,
+    ktype: str = "K_DAY",
+    start: str | None = None,
+    end: str | None = None,
+    max_count: int = 100,
+    autype: str = "QFQ",
+) -> list[dict]:
+    """Get historical candlestick (K-line) data for a stock.
+
+    Returns OHLCV (Open, High, Low, Close, Volume) data for technical analysis.
+
+    Args:
+        code: Stock code (e.g., 'US.AAPL').
+        ktype: K-line type. Options:
+            - K_1M: 1 minute
+            - K_3M: 3 minutes
+            - K_5M: 5 minutes
+            - K_15M: 15 minutes
+            - K_30M: 30 minutes
+            - K_60M: 60 minutes
+            - K_DAY: Daily (default)
+            - K_WEEK: Weekly
+            - K_MON: Monthly
+            - K_QUARTER: Quarterly
+            - K_YEAR: Yearly
+        start: Start date in YYYY-MM-DD format. Defaults to 365 days before end.
+        end: End date in YYYY-MM-DD format. Defaults to today.
+        max_count: Maximum number of candles to return (default 100, max 1000).
+        autype: Adjustment type for splits/dividends:
+            - QFQ: Forward adjustment (default)
+            - HFQ: Backward adjustment
+            - NONE: No adjustment
+
+    Returns:
+        List of K-line dictionaries containing:
+        - time_key: Candlestick timestamp
+        - open: Open price
+        - high: High price
+        - low: Low price
+        - close: Close price
+        - volume: Volume
+        - turnover: Turnover
+        - change_rate: Price change rate
+    """
+    market_data_service = ctx.request_context.lifespan_context.market_data_service
+    klines = market_data_service.get_historical_klines(
+        code=code,
+        ktype=ktype,
+        start=start,
+        end=end,
+        max_count=max_count,
+        autype=autype,
+    )
+    await ctx.info(f"Retrieved {len(klines)} K-lines for {code}")
+    return klines
+
+
+@mcp.tool()
+async def get_market_snapshot(
+    ctx: Context[ServerSession, AppContext],
+    codes: list[str],
+) -> list[dict]:
+    """Get market snapshot for multiple stocks efficiently.
+
+    This is ideal for checking current status of a watchlist without subscription.
+    Returns comprehensive market data including price, volume, and fundamentals.
+
+    Args:
+        codes: List of stock codes (up to 400). E.g., ['US.AAPL', 'US.TSLA', 'HK.00700'].
+
+    Returns:
+        List of snapshot dictionaries containing:
+        - code: Stock code
+        - name: Stock name
+        - last_price: Latest price
+        - open_price: Open price
+        - high_price: High price
+        - low_price: Low price
+        - prev_close_price: Previous close
+        - volume: Trading volume
+        - turnover: Turnover amount
+        - turnover_rate: Turnover rate (%)
+        - pe_ratio: P/E ratio
+        - pb_ratio: P/B ratio
+        - And many more fields
+    """
+    market_data_service = ctx.request_context.lifespan_context.market_data_service
+    snapshots = market_data_service.get_market_snapshot(codes)
+    await ctx.info(f"Retrieved snapshots for {len(codes)} stocks")
+    return snapshots
+
+
+@mcp.tool()
+async def get_order_book(
+    ctx: Context[ServerSession, AppContext],
+    code: str,
+    num: int = 10,
+) -> dict:
+    """Get order book (market depth) showing bid/ask price levels.
+
+    Returns the top N bid and ask levels with prices and volumes.
+    Useful for analyzing liquidity and market sentiment.
+    Automatically subscribes to the stock before fetching order book.
+
+    Args:
+        code: Stock code (e.g., 'HK.00700', 'US.AAPL').
+        num: Number of price levels to return (default 10).
+
+    Returns:
+        Dictionary containing:
+        - code: Stock code
+        - Bid: List of bid levels, each as (price, volume, order_count, details)
+        - Ask: List of ask levels, each as (price, volume, order_count, details)
+    """
+    market_data_service = ctx.request_context.lifespan_context.market_data_service
+    order_book = market_data_service.get_order_book(code, num=num)
+    await ctx.info(f"Retrieved order book for {code} with {num} levels")
+    return order_book
+
+
+@mcp.tool()
+async def get_user_security_group(
+    ctx: Context[ServerSession, AppContext],
+    group_type: int = 0,
+) -> list[dict]:
+    """Get list of user-defined security groups (watchlists).
+
+    Returns the user's custom watchlist groups from the Moomoo app.
+
+    Args:
+        group_type: Type of groups to return. Options:
+            - 0: All groups (default)
+            - 1: Custom groups only
+            - 2: System groups only
+
+    Returns:
+        List of group dictionaries containing:
+        - group_name: Name of the group
+        - group_id: Unique identifier for the group
+    """
+    market_data_service = ctx.request_context.lifespan_context.market_data_service
+    groups = market_data_service.get_user_security_group(group_type=group_type)
+    await ctx.info(f"Retrieved {len(groups)} security groups")
+    return groups
+
+
+@mcp.tool()
+async def get_user_security(
+    ctx: Context[ServerSession, AppContext],
+    group_name: str,
+) -> list[dict]:
+    """Get list of securities in a specific user-defined group (watchlist).
+
+    Returns all stocks/securities that the user has added to a specific watchlist.
+
+    Args:
+        group_name: Name of the security group (e.g., 'Favorites', 'Tech').
+
+    Returns:
+        List of security dictionaries containing:
+        - code: Stock code (e.g., 'US.AAPL')
+        - name: Stock name
+        - lot_size: Lot size for trading
+        - stock_type: Type of security
+    """
+    market_data_service = ctx.request_context.lifespan_context.market_data_service
+    securities = market_data_service.get_user_security(group_name)
+    await ctx.info(f"Retrieved {len(securities)} securities from group '{group_name}'")
+    return securities

moomoo_mcp/tools/system.py

@@ -0,0 +1,20 @@
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+
+from moomoo_mcp.server import AppContext, mcp
+
+@mcp.tool()
+async def check_health(
+    ctx: Context[ServerSession, AppContext]
+) -> dict[str, str]:
+    """Check connectivity to Moomoo and MCP server health.
+
+    Returns:
+        Dictionary containing status and connection info.
+    """
+    moomoo_service = ctx.request_context.lifespan_context.moomoo_service
+    status = moomoo_service.check_health()
+    
+    await ctx.info(f"Health check status: {status.get('status')}")
+    
+    return status