futu-stock

This MCP server implements the Futu Stock MCP server, exposing Futu OpenAPI capabilities through the MCP 2.0 protocol. It enables real-time market data subscription, quotes, historical K-line data, and account-related queries, with the option to perform trading actions depending on permissions. Clients interact via MCP-compatible transports (e.g., stdio, IPC) and can list available tools, then call them by name to retrieve data or invoke actions. Typical workflow: start the server, connect with an MCP client, call list_tools to discover available endpoints (like get_stock_quote, subscribe_quotes, get_kline, get_account_info, etc.), then use call_tool to perform a specific operation and receive structured responses according to MCP schemas.

Prerequisites:

• Python 3.10+ (recommended)
• Futu OpenAPI SDK installed
• Model Context Protocol (MCP) SDK as needed by your client
• Optional uv (for development) for local environment management

Installation steps (from source):

1. Clone the repository:

git clone https://github.com/yourusername/futu-stock-mcp-server.git
cd futu-stock-mcp-server

2. Create and activate a Python environment (optional but recommended):

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

3. Install the package (editable mode preferred for development):

pip install -e .

4. Install uv if you are running in development mode (optional):

pip install uv

5. Ensure required environment variables are set when running in source mode (see MCP Server configuration for details). If running via pipx, you can install and run the server with:

pipx install futu-stock-mcp-server
futu-mcp-server

Optional from-source run (via module):

python -m futu_stock_mcp_server.server

Tips and common considerations:

• Use MCP client env injections to avoid .env files; configure FUTU_HOST, FUTU_PORT, and other options via the mcpServers config or the client env field.
• Ensure OpenD gateway is running and accessible at the configured host/port.
• Logs are written to logs/futu_server.log with rotation; check if you encounter connection or authentication issues.
• If commands like futu-mcp-server are not found, verify PATH or use the full path to the executable or Python module invocations as shown in the README examples.
• For troubleshooting, verify that FUTU_HOST and FUTU_PORT values match your OpenD gateway configuration and that network access is allowed between processes.
• When running in production, consider setting FUTU_DEBUG_MODE to 0 to reduce verbose logs; enable it only for debugging.
• The server supports multiple markets (HK/US) and requires proper subscription of market data permissions from Futu OpenAPI.
• If you configure via MCP client, prefer env injections in the client configuration rather than shipping .env files in source control.