An MCP (Model Context Protocol) server for the Moomoo trading platform. This server allows AI agents (like Claude Desktop or Gemini) to access market data, account information, and execute trades via the moomoo-api Python SDK.
- Market Data: Real-time quotes, historical K-lines, market snapshots, and order books.
- Account Management: Comprehensive account summaries, assets, positions, and cash flow analysis.
- Trading: Full order management including placing, modifying, and canceling orders.
- System Health: Built-in health checks and connectivity verification.
- Extensible Architecture: Built on FastMCP for easy extension of trading capabilities.
check_health: Check connectivity to Moomoo OpenD gateway and server health.
get_accounts: List all trading accounts (REAL and SIMULATE).get_account_summary: Get a complete summary of assets and positions for an account.get_assets: Retrieve account assets (cash, market value, buying power).get_positions: Get current stock positions with P/L data.get_max_tradable: Calculate maximum tradable quantity for a specific stock.get_margin_ratio: Check margin ratios for specific stocks.get_cash_flow: Retrieve historical cash flow records.unlock_trade: Unlock trading access for REAL accounts.
get_stock_quote: Get real-time stock quotes.get_historical_klines: Retrieve historical candlestick data (Day, Week, Min, etc.).get_market_snapshot: Get efficient market snapshots for multiple stocks.get_order_book: View real-time bid/ask order book depth.
place_order: Place a new order (Market, Limit, Stop, etc.).modify_order: Modify price or quantity of an open order.cancel_order: Cancel an open order.get_orders: Get list of orders for the current day.get_deals: Get list of executed trades (deals) for the current day.get_history_orders: Search historical orders.get_history_deals: Search historical deals.
You can run the server directly using uvx (part of the uv toolkit).
Using --refresh ensures you are always running the latest version:
uvx --refresh moomoo-api-mcpTo install it as a persistent tool available in your shell:
uv tool install moomoo-api-mcp
# Then run:
moomoo-api-mcpNote: The
moomoo-apiPython SDK and other dependencies will be installed automatically.
-
Clone the repository:
git clone https://github.com/Litash/moomoo-api-mcp.git cd moomoo-api-mcp -
Install dependencies:
uv sync
-
Run locally:
uv run moomoo-api-mcp
The MCP server communicates with the Moomoo API via Moomoo OpenD, a local gateway application. You MUST install and run this first.
-
Download OpenD:
- Visit the Moomoo Open API Download Page.
- Download the version appropriate for your OS (Windows/Mac/Linux).
-
Install & Run:
- Install the application.
- Launch Moomoo OpenD.
- Log in with your Moomoo account credentials.
-
Configure:
- Ensure the listening port is set to
11111(this is the default). - Note: The MCP server connects to
127.0.0.1:11111by default.
- Ensure the listening port is set to
To enable REAL account access, you must securely provide your credentials.
| Variable | Description | Example |
|---|---|---|
MOOMOO_TRADE_PASSWORD |
Your trading password (plain text) | 123456 |
MOOMOO_SECURITY_FIRM |
Your broker region (e.g., FUTUSG, FUTUINC) | FUTUSG |
Note: Without these, the server runs in SIMULATE-only mode (paper trading).
Add the server to your claude_desktop_config.json:
{
"mcpServers": {
"moomoo": {
"command": "uvx",
"args": ["--refresh", "moomoo-api-mcp"],
"env": {
"MOOMOO_TRADE_PASSWORD": "your_trading_password",
"MOOMOO_SECURITY_FIRM": "FUTUSG"
}
}
}
}Note: The
--refreshflag ensures you always have the latest version but may increase startup time due to version checking. You can remove it once you have the correct version installed.
{
"mcpServers": {
"moomoo": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\moomoo-api-mcp",
"run",
"moomoo-api-mcp"
],
"env": {
"MOOMOO_TRADE_PASSWORD": "your_trading_password",
"MOOMOO_SECURITY_FIRM": "FUTUSG"
}
}
}
}Security: Never commit your password to version control. The
envblock in the config file remains local.
IMPORTANT: All account tools default to REAL trading accounts.
When using this MCP server, AI agents MUST:
-
Notify the user clearly before accessing REAL account data. Example:
"I'm about to access your REAL trading account. This will show your actual portfolio and balances."
-
Follow the unlock workflow for REAL accounts:
- First call
unlock_trade(it handles env vars automatically, or pass password if needed). - Then call account/trading tools (they default to
trd_env='REAL').
- First call
-
Only use SIMULATE accounts when explicitly requested by the user. To use simulation:
- Pass
trd_env='SIMULATE'parameter explicitly. - No unlock is required for simulation accounts.
- Pass
User: "Show me my portfolio"
Agent Response:
"I'm accessing your REAL trading account to show your portfolio.
If you prefer to use a simulation account instead, please let me know."
[Proceeds to unlock_trade → get_account_summary]
When using get_orders or get_history_orders, the status_filter_list parameter accepts an array of string values:
["SUBMITTED", "FILLED_ALL", "CANCELLED_ALL"]Valid status strings:
UNSUBMITTED,WAITING_SUBMIT,SUBMITTING,SUBMIT_FAILEDSUBMITTED,FILLED_PART,FILLED_ALLCANCELLING_PART,CANCELLING_ALL,CANCELLED_PART,CANCELLED_ALLREJECTED,DISABLED,DELETED,FAILED,NONE
Note: The server automatically converts these strings to the required SDK enum format. If no orders match the filter, an empty list is returned.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Unofficial Project: This software is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Moomoo Inc., Futu Holdings Ltd., or their affiliates.
- Use at your own risk: Trading involves financial risk. The authors provide this software "as is" without warranty of any kind.
- Test First: Always test your agents and tools in the Simulation (Paper Trading) environment before using real funds.