wliant/moomoo-mcp

Moomoo MCP Server

A Model Context Protocol (MCP) server that provides integration with the Moomoo/Futu OpenAPI for stock market data and trading operations.

Features

The Moomoo MCP server exposes the following tools through the MCP protocol:

Market Data Tools

• get_stock_quote - Get real-time stock quotes
• get_market_snapshot - Get comprehensive market data for multiple stocks
• get_history_kline - Retrieve historical K-line/candlestick data
• get_order_book - Access real-time bid/ask order book data
• get_plate_list - List sectors/plates in a market
• get_plate_stock - Get stocks within a specific sector
• get_option_chain - Retrieve option chain data
• get_trading_days - Get trading calendar information
• get_stock_basicinfo - Get basic stock information
• subscribe_quotes - Subscribe to real-time quote updates
• unsubscribe_quotes - Unsubscribe from quote updates

Connection Management

• moomoo_connect - Connect to FutuOpenD gateway
• moomoo_disconnect - Disconnect from gateway

Prerequisites

1. FutuOpenD Gateway: You need to have FutuOpenD installed and running. Download it from Futu OpenAPI.

2. Python 3.8+: The server requires Python 3.8 or higher.

3. Moomoo Account: You'll need a Moomoo account to use the API (for real trading data).

Installation

From Source

1. Clone the repository:

git clone <repository-url>
cd moomoo-mcp

2. Install dependencies:

pip install -r requirements.txt

3. Install the package in development mode:

pip install -e .

Configuration

The server can be configured using environment variables:

• MOOMOO_HOST: FutuOpenD gateway host (default: 127.0.0.1)
• MOOMOO_PORT: FutuOpenD gateway port (default: 11111)
• MOOMOO_ENCRYPT: Use encrypted connection (default: false)

Usage

Running the Server Standalone

python -m src.moomoo_mcp.server

Integrating with MCP Clients

To use this server with an MCP client (like Claude Desktop or Cline), add it to your MCP settings configuration:

For Cline (VSCode)

Add to ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "moomoo": {
      "command": "python",
      "args": ["-m", "src.moomoo_mcp.server"],
      "cwd": "/path/to/moomoo-mcp",
      "env": {
        "MOOMOO_HOST": "127.0.0.1",
        "MOOMOO_PORT": "11111",
        "MOOMOO_ENCRYPT": "false"
      }
    }
  }
}

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "moomoo": {
      "command": "python",
      "args": ["-m", "src.moomoo_mcp.server"],
      "cwd": "/path/to/moomoo-mcp",
      "env": {
        "MOOMOO_HOST": "127.0.0.1",
        "MOOMOO_PORT": "11111"
      }
    }
  }
}

Example Usage

Once the server is connected to an MCP client, you can use the tools like this:

Connect to Gateway

Use the moomoo_connect tool to connect to the FutuOpenD gateway

Get Stock Quote

Use get_stock_quote with code_list: ["HK.00700", "US.AAPL"]

Get Historical Data

Use get_history_kline with:
- code: "HK.00700"
- start: "2024-01-01"
- end: "2024-01-31"
- ktype: "K_DAY"

Subscribe to Real-time Updates

Use subscribe_quotes with:
- code_list: ["HK.00700"]
- subtype_list: ["QUOTE", "TICKER"]

Development

Running Tests

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=src/moomoo_mcp

# Run specific test file
pytest tests/test_moomoo_client.py

# Run only unit tests (skip integration tests)
pytest -m "not integration"

Code Formatting

Format code using Black:

black src/ tests/

Type Checking

Run type checking with mypy:

mypy src/

API Documentation

Tool Parameters

get_stock_quote

• code_list (array): List of stock codes, e.g., ["HK.00700", "US.AAPL"]

get_history_kline

• code (string): Stock code
• start (string, optional): Start date (YYYY-MM-DD)
• end (string, optional): End date (YYYY-MM-DD)
• ktype (string): K-line type - K_DAY, K_WEEK, K_MON, K_1M, K_5M, etc.
• autype (string): Adjustment type - QFQ (forward), HFQ (backward), NONE
• max_count (integer): Maximum number of records

get_order_book

• code (string): Stock code
• num (integer): Number of levels (max 10 for LV2, 40 for SF)

get_plate_list

• market (string): Market - HK, US, SH, SZ
• plate_class (string): Plate class - ALL, INDUSTRY, REGION, CONCEPT

get_option_chain

• code (string): Underlying stock code
• start (string, optional): Start date for expiration
• end (string, optional): End date for expiration
• option_type (string): Option type - ALL, CALL, PUT
• option_cond_type (string): Option condition - ALL, WITHIN, OUTSIDE

Troubleshooting

Connection Issues

1. Ensure FutuOpenD is running: The gateway must be running before starting the MCP server.

2. Check firewall settings: Make sure port 11111 (or your configured port) is accessible.

3. Verify API permissions: Ensure your Moomoo account has API access enabled.

Common Errors

• "Not connected to gateway": Use the moomoo_connect tool first
• "Subscribe failed": Check if you have reached subscription limits
• "API Error": Check FutuOpenD logs for detailed error messages

Limitations

• Real-time data subscriptions are limited based on your account type
• Historical data queries have daily limits
• Some features require specific market data permissions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

For issues related to:

• MCP Server: Open an issue in this repository
• Moomoo API: Refer to Moomoo OpenAPI Documentation
• FutuOpenD: Check the Futu OpenAPI Documentation

Disclaimer

This software is for educational and research purposes only. Always follow your broker's terms of service and applicable regulations when using market data and trading APIs.