Futu Stock MCP Server

Futu Stock MCP Server

モデルコンテキストプロトコル（MCP）に基づく、Futu証券の相場・取引インターフェースサーバーです。Futu OpenAPIの機能を標準化されたMCPプロトコルでAIモデルに提供し、相場の購読やデータの照会などをサポートします。

🌟 特長

• 🔌 MCP 2.0プロトコル標準に完全準拠
• 📊 香港株、米国株、A株などの市場のリアルタイム相場をサポート
• 🔄 リアルタイムデータの購読とプッシュ通知をサポート
• 📈 ローソク足、ティック、売買板など、多角的なデータをサポート
• 🔒 安全なAPI呼び出しとデータアクセスの仕組み
• 🛠 充実した開発ツールとサンプルコードを提供

⚠️ 前提条件

このプロジェクトを使用する前に、以下が必要です。

1. Futu証券の口座を所有し、OpenAPIの権限を有効にしていること
2. FutuのOpenDゲートウェイプログラムをインストールして実行していること（公式ドキュメント）
3. 必要に応じて、該当する相場情報の権限を購読していること

🔒 セキュリティに関する注意

• コードにアカウントやパスワードの情報をハードコードしないでください
• .envファイルが.gitignoreに追加されていることを確認してください
• APIアクセス認証情報を適切に管理してください
• Futu OpenAPIの利用規約と制限を遵守してください

📝 免責事項

このプロジェクトは、Futu OpenAPIの導入プロセスを簡素化することを目的としたオープンソースツールです。このプロジェクトを使用する際は、以下にご注意ください。

1. 関連法令およびFutu OpenAPIの利用規約を遵守してください
2. このプロジェクトを使用した取引のリスクは、ご自身で負担してください
3. このプロジェクトは投資アドバイスを提供しません
4. このプロジェクトを使用する前に、必要な相場情報の権限を取得していることを確認してください

特長

• MCP 2.0プロトコルに準拠
• Futu APIを幅広くカバー
• リアルタイムデータの購読をサポート
• 市場データへのアクセス
• デリバティブ情報
• 口座情報の照会機能
• リソースベースのデータアクセス
• 分析用の対話型プロンプト

前提条件

• Python 3.10+
• Futu OpenAPI SDK
• Model Context Protocol SDK
• uv（推奨）

🚀 クイックスタート

方法 1：pipx でインストール（推奨）

# 安装 pipx（如果还没有安装）
brew install pipx  # macOS
# 或者 pip install --user pipx  # 其他系统

# 安装包
pipx install futu-stock-mcp-server

# 运行服务器
futu-mcp-server

pipxを使用する理由

• pipxは、Pythonアプリケーションをグローバル環境にインストールするためのツールです
• 仮想環境を自動的に個別に管理し、依存関係の競合を防ぎます
• 仮想環境を有効化しなくても、コマンドをそのまま使用できます

方法 2：Docker で実行

# 拉取镜像
docker pull your-registry/futu-stock-mcp-server:latest

# 运行容器
docker run -d \
  --name futu-mcp-server \
  -p 8000:8000 \
  -e FUTU_HOST=127.0.0.1 \
  -e FUTU_PORT=11111 \
  your-registry/futu-stock-mcp-server:latest

方法 3：ソースからインストール

1. リポジトリをクローンします。

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

2. uvをインストールします。

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 仮想環境を作成して有効化します。

# Create virtual environment
uv venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. 依存関係をインストールします。

# Install in editable mode
uv pip install -e .

5. （任意）ソースから直接実行する場合は、環境変数でサービスを設定します。

export FUTU_HOST=127.0.0.1
export FUTU_PORT=11111

推奨方法：MCPクライアントの設定ファイルでenvフィールドを使用して値を渡せば、.envファイルを作成する必要はありません。下記のMCP サーバーの設定のセクションを参照してください。

開発

依存関係の管理

新しい依存関係をpyproject.tomlに追加します。

[project]
dependencies = [
    # ... existing dependencies ...
    "new-package>=1.0.0",
]

次に、環境を更新します。

uv pip install -e .

コードスタイル

このプロジェクトでは、コードのリントとフォーマットにRuffを使用しています。設定はpyproject.tomlにあります。

[tool.ruff]
line-length = 100
target-version = "py38"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "B", "UP"]

リントを実行します。

uv pip install ruff
ruff check .

フォーマットを実行します。

ruff format .

🔧 MCP サーバーの設定

Claude Desktop での設定

1. 設定ファイルの場所を確認します：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. サーバー設定を追加します（すべてのパラメーターはenvフィールドで渡すため、.envファイルは不要です）。

{
  "mcpServers": {
    "futu-stock": {
      "command": "futu-mcp-server",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111",
        "FUTU_ENABLE_POSITIONS": "1",
        "FUTU_ENABLE_TRADING": "0",
        "FUTU_TRADE_ENV": "SIMULATE",
        "FUTU_SECURITY_FIRM": "FUTUSECURITIES",
        "FUTU_TRD_MARKET": "HK"
      }
    }
  }
}

3. pythonコマンドを使用して起動します（ソースコードで開発する場合に適しています）。

{
  "mcpServers": {
    "futu-stock": {
      "command": "python",
      "args": ["-m", "futu_stock_mcp_server.server"],
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

4. トラブルシューティング用の設定： 上記の設定で動作しない場合は、絶対パスを指定してみてください。

{
  "mcpServers": {
    "futu-stock": {
      "command": "/Users/your-username/.local/bin/futu-mcp-server",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

ヒント：which futu-mcp-serverコマンドを使用して、絶対パスを確認できます

その他の MCP クライアントでの設定

Python MCP クライアントを使用

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="futu-mcp-server",
        env={
            "FUTU_HOST": "127.0.0.1",
            "FUTU_PORT": "11111"
        }
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print("Available tools:", [tool.name for tool in tools.tools])

Node.js MCP クライアントを使用

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "futu-mcp-server",
  env: {
    FUTU_HOST: "127.0.0.1",
    FUTU_PORT: "11111"
  }
});

const client = new Client({
  name: "futu-stock-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);

📋 使用方法

1. サーバーを起動する（単独で実行）

# 通过 pip 安装后
futu-mcp-server

# 或从源码运行
python -m futu_stock_mcp_server.server

2. 環境変数の設定

MCPクライアントのenvフィールドで直接設定することを推奨します。.envファイルは不要です。

環境変数	説明	デフォルト値
FUTU_HOST	OpenDのアドレス	127.0.0.1
FUTU_PORT	OpenDのポート	11111
FUTU_TRADE_ENV	取引環境（SIMULATE/REAL）	SIMULATE
FUTU_SECURITY_FIRM	証券会社（FUTUSECURITIES/FUTUINC）	FUTUSECURITIES
FUTU_TRD_MARKET	取引市場（HK/US）	HK
FUTU_DEBUG_MODE	デバッグログの切り替え（0/1）	0

3. 接続を確認する

サーバーの起動後、次のようなログが表示されます。

2024-10-02 14:20:52 | INFO | Initializing Futu connection...
2024-10-02 14:20:52 | INFO | Successfully initialized Futu connection
2024-10-02 14:20:52 | INFO | Starting MCP server in stdio mode...
2024-10-02 14:20:52 | INFO | Press Ctrl+C to stop the server

4. AI ツールで使用する

設定が完了したら、Claude Desktopまたはその他のMCPクライアントを再起動します。次の操作ができます。

• 株式のリアルタイム相場を照会する
• 過去のローソク足データを取得する
• 株式データのプッシュ通知を購読する
• 口座情報を照会する
• 取引を実行する（取引権限が必要です）

🔧 トラブルシューティング

よくある問題

1. futu-mcp-serverコマンドが見つからない

# 确保已正确安装
pipx install futu-stock-mcp-server

# 检查命令是否可用
which futu-mcp-server

# 如果还是找不到，检查 PATH
echo $PATH | grep -o '[^:]*\.local/bin[^:]*'

2. Ctrl+Cでサーバーを終了できない

• 新しいバージョンではこの問題は修正されています
• それでも発生する場合は、kill -9 <pid>を使用して強制終了できます

3. Futu OpenDへの接続に失敗する

# 检查 OpenD 是否运行
netstat -an | grep 11111

# 检查环境变量
echo $FUTU_HOST
echo $FUTU_PORT

4. Claude Desktopがサーバーを認識しない

• 設定ファイルのパスが正しいことを確認してください
• JSON形式が有効であることを確認してください
• Claude Desktopを再起動してください
• Claude Desktopのログファイルを確認してください

5. 権限の問題

# 确保有执行权限
chmod +x ~/.local/bin/futu-mcp-server

# 或者使用完整路径
python -m futu_stock_mcp_server.server

ログのデバッグ

このプロジェクトでは、MCP公式ドキュメントのベストプラクティスに基づいて、ログシステムを設定しています。

MCPに対応したログ設定

• ファイルログ：すべてのログはlogs/futu_server.logに書き込まれ、自動的にローテーションとクリーンアップが行われます
• MCP Contextログ：ツールの実行中、MCP Contextを介してクライアントにログを送信します
• stdoutの保護：stdoutはMCPのJSON通信専用とし、他の出力が混入しないようにします

デバッグモード（開発時のみ使用）

# 启用调试模式（会向 stderr 输出日志）
export FUTU_DEBUG_MODE=1
futu-mcp-server

注意：MCPクライアントではデバッグモードを有効にしないでください。ログがstderrに出力されるためです。

ログファイルの場所

• メインログファイル：./logs/futu_server.log
• 自動ローテーション：500 MB ごとにローテーションします
• 自動クリーンアップ：10 日間保持します

ログ設定の詳細については、docs/LOGGING.md を参照してください。 tools = await session.list_tools()

        # Call a tool
        result = await session.call_tool(
            "get_stock_quote",
            arguments={"symbols": ["HK.00700"]}
        )
        
        # Access a resource
        content, mime_type = await session.read_resource(
            "market://HK.00700"
        )
        
        # Get a prompt
        prompt = await session.get_prompt(
            "market_analysis",
            arguments={"symbol": "HK.00700"}
        )

if name == "main": import asyncio asyncio.run(main())

## Changelog

Latest updates (`2026-03-02`) - v0.1.5:
- **环境变量优先配置**：`FUTU_HOST` / `FUTU_PORT` 现在直接通过 MCP 客户端 `env` 字段注入，无需 `.env` 文件。
- 移除 `python-dotenv` 导入，简化依赖。
- 新增 `python -m` 启动方式的配置示例。

Previous updates (`2026-03-02`) - v0.1.4:
- Added trading MCP tools: `unlock_trade`, `place_order`, `modify_order`, `cancel_order`, `cancel_all_orders`, order/deal query tools, fee/cashflow tools.
- Added position and trade feature switches: `FUTU_ENABLE_POSITIONS`, `FUTU_ENABLE_TRADING`.
- Added official Futu API to MCP mapping doc: [docs/FUTU_API_MCP_COVERAGE.md](docs/FUTU_API_MCP_COVERAGE.md).
- Kept backward compatibility: existing MCP tool names and argument contracts were not changed.

Full history: [CHANGELOG.md](CHANGELOG.md)

## Available API Methods

Full mapping document (official Futu API -> MCP tools): [docs/FUTU_API_MCP_COVERAGE.md](docs/FUTU_API_MCP_COVERAGE.md)

### Market Data Tools
- `get_stock_quote`: Get stock quote data
- `get_market_snapshot`: Get market snapshot
- `get_cur_kline`: Get current K-line data
- `get_history_kline`: Get historical K-line data
- `get_rt_data`: Get real-time data
- `get_ticker`: Get ticker data
- `get_order_book`: Get order book data
- `get_broker_queue`: Get broker queue data

### Subscription Tools
- `subscribe`: Subscribe to real-time data
- `unsubscribe`: Unsubscribe from real-time data

### Derivatives Tools
- `get_option_chain`: Get option chain data
- `get_option_expiration_date`: Get option expiration dates
- `get_option_condor`: Get option condor strategy data
- `get_option_butterfly`: Get option butterfly strategy data

### Account Query Tools
- `get_account_list`: Get account list
- `get_funds`: Get account funds information
- `get_positions`: Get account positions
- `get_position_list`: Get account positions with filters
- `get_max_power`: Get account buying power
- `get_margin_ratio`: Get margin ratio for a security

### Trading Tools
- `unlock_trade`: Unlock trade operations
- `place_order`: Place order
- `modify_order`: Modify order
- `cancel_order`: Cancel one order
- `cancel_all_orders`: Cancel all cancellable orders
- `get_order_list`: Query current order list
- `get_history_order_list`: Query historical orders
- `get_deal_list`: Query current deals
- `get_history_deal_list`: Query historical deals
- `get_order_fee`: Query order fee details
- `get_acc_cash_flow`: Query cash flow details
- `get_acc_trading_info`: Query trade capability/pre-check

### Market Information Tools
- `get_market_state`: Get market state
- `get_security_info`: Get security information
- `get_security_list`: Get security list

### Stock Filter Commands

#### get_stock_filter
Filter stocks based on various conditions.

Parameters:
- `base_filters` (optional): List of basic stock filters
  ```python
  {
      "field_name": int,  # StockField enum value
      "filter_min": float,  # Optional minimum value
      "filter_max": float,  # Optional maximum value
      "is_no_filter": bool,  # Optional, whether to skip filtering
      "sort_dir": int  # Optional, sort direction
  }

• accumulate_filters（任意）：累積フィルターのリスト

  {
      "field_name": int,  # AccumulateField enum value
      "filter_min": float,
      "filter_max": float,
      "is_no_filter": bool,
      "sort_dir": int,
      "days": int  # Required, number of days to accumulate
  }
  

• financial_filters（任意）：財務フィルターのリスト

  {
      "field_name": int,  # FinancialField enum value
      "filter_min": float,
      "filter_max": float,
      "is_no_filter": bool,
      "sort_dir": int,
      "quarter": int  # Required, financial quarter
  }
  

• market（任意）：市場コード（例："HK.Motherboard"、"US.NASDAQ"）
• page（任意）：ページ番号。1 から開始します（デフォルト：1）
• page_size（任意）：1 ページあたりの結果数。最大 200 です（デフォルト：200）

サポートされている市場コード：

• HK.Motherboard：香港メインボード
• HK.GEM：香港 GEM
• HK.BK1911：H 株メインボード
• HK.BK1912：H 株 GEM
• US.NYSE：NYSE
• US.AMEX：AMEX
• US.NASDAQ：NASDAQ
• SH.3000000：上海メインボード
• SZ.3000001：深圳メインボード
• SZ.3000004：深圳 ChiNext

例：

# Get stocks with price between 10 and 50 HKD in Hong Kong Main Board
filters = {
    "base_filters": [{
        "field_name": 5,  # Current price
        "filter_min": 10.0,
        "filter_max": 50.0
    }],
    "market": "HK.Motherboard"
}
result = await client.get_stock_filter(**filters)

注：

• 30 秒あたりのリクエスト数は 10 回に制限されています
• 各ページで返される結果は最大 200 件です
• フィルター条件は 250 件以下にすることを推奨します
• 同じ種類の累積条件は最大 10 件です
• 現在価格などの動的データは、ページ間で変わる場合があります
• 異なる種類の指標（例：MA5 と EMA10）は比較できません

リソース

市場データ

• market://{symbol}：シンボルの市場データを取得します
• kline://{symbol}/{ktype}：シンボルの K ラインデータを取得します

プロンプト

分析

• market_analysis：市場分析プロンプトを作成します
• option_strategy：オプション戦略分析プロンプトを作成します

エラー処理

このサーバーは MCP 2.0 のエラーレスポンス形式に準拠しています：

{
    "jsonrpc": "2.0",
    "id": "request_id",
    "error": {
        "code": -32000,
        "message": "Error message",
        "data": null
    }
}

セキュリティ

• サーバーは安全な WebSocket 接続を使用します
• すべての API 呼び出しは Futu OpenAPI を通じて認証されます
• 機密設定には環境変数を使用します

開発

新しいツールの追加

新しいツールを追加するには、@mcp.tool() デコレーターを使用します：

@mcp.tool()
async def new_tool(param1: str, param2: int) -> Dict[str, Any]:
    """Tool description"""
    # Implementation
    return result

新しいリソースの追加

新しいリソースを追加するには、@mcp.resource() デコレーターを使用します：

@mcp.resource("resource://{param1}/{param2}")
async def new_resource(param1: str, param2: str) -> Dict[str, Any]:
    """Resource description"""
    # Implementation
    return result

新しいプロンプトの追加

新しいプロンプトを追加するには、@mcp.prompt() デコレーターを使用します：

@mcp.prompt()
async def new_prompt(param1: str) -> str:
    """Prompt description"""
    return f"Prompt template with {param1}"

ライセンス

MIT ライセンス

利用可能な MCP 関数

市場データ関数

get_stock_quote

指定されたシンボルの株価データを取得します。

symbols = ["HK.00700", "US.AAPL", "SH.600519"]
result = await session.call_tool("get_stock_quote", {"symbols": symbols})

価格、出来高、売買代金などを含む株価データを返します。

get_market_snapshot

指定されたシンボルのマーケットスナップショットを取得します。

symbols = ["HK.00700", "US.AAPL", "SH.600519"]
result = await session.call_tool("get_market_snapshot", {"symbols": symbols})

価格、出来高、買値／売値などを含む包括的な市場データを返します。

get_cur_kline

現在の K ラインデータを取得します。

result = await session.call_tool("get_cur_kline", {
    "symbol": "HK.00700",
    "ktype": "K_1M",  # K_1M, K_5M, K_15M, K_30M, K_60M, K_DAY, K_WEEK, K_MON
    "count": 100
})

get_history_kline

過去の K ラインデータを取得します。

result = await session.call_tool("get_history_kline", {
    "symbol": "HK.00700",
    "ktype": "K_DAY",
    "start": "2024-01-01",
    "end": "2024-03-31"
})

get_rt_data

リアルタイム取引データを取得します。

result = await session.call_tool("get_rt_data", {"symbol": "HK.00700"})

get_ticker

ティッカーデータ（詳細な取引）を取得します。

result = await session.call_tool("get_ticker", {"symbol": "HK.00700"})

get_order_book

板情報を取得します。

result = await session.call_tool("get_order_book", {"symbol": "HK.00700"})

get_broker_queue

ブローカーキューのデータを取得します。

result = await session.call_tool("get_broker_queue", {"symbol": "HK.00700"})

サブスクリプション関数

subscribe

リアルタイムデータを購読します。

result = await session.call_tool("subscribe", {
    "symbols": ["HK.00700", "US.AAPL"],
    "sub_types": ["QUOTE", "TICKER", "K_1M"]
})

サブスクリプションの種類：

• "QUOTE"：基本株価
• "ORDER_BOOK"：板情報
• "TICKER"：取引
• "RT_DATA"：リアルタイムデータ
• "BROKER"：ブローカーキュー
• "K_1M" から "K_MON"：K ラインデータ

unsubscribe

リアルタイムデータの購読を解除します。

result = await session.call_tool("unsubscribe", {
    "symbols": ["HK.00700", "US.AAPL"],
    "sub_types": ["QUOTE", "TICKER"]
})

オプション関数

get_option_chain

オプションチェーンのデータを取得します。

result = await session.call_tool("get_option_chain", {
    "symbol": "HK.00700",
    "start": "2024-04-01",
    "end": "2024-06-30"
})

get_option_expiration_date

オプションの有効期限を取得します。

result = await session.call_tool("get_option_expiration_date", {
    "symbol": "HK.00700"
})

get_option_condor

オプションのコンドル戦略データを取得します。

result = await session.call_tool("get_option_condor", {
    "symbol": "HK.00700",
    "expiry": "2024-06-30",
    "strike_price": 350.0
})

get_option_butterfly

オプションのバタフライ戦略データを取得します。

result = await session.call_tool("get_option_butterfly", {
    "symbol": "HK.00700",
    "expiry": "2024-06-30",
    "strike_price": 350.0
})

アカウント関数

get_account_list

口座一覧を取得します。

result = await session.call_tool("get_account_list", {"random_string": "dummy"})

get_funds

口座の資金情報を取得します。

result = await session.call_tool("get_funds", {"random_string": "dummy"})

get_positions

口座のポジションを取得します。

result = await session.call_tool("get_positions", {"random_string": "dummy"})

get_max_power

最大取引可能額を取得します。

result = await session.call_tool("get_max_power", {"random_string": "dummy"})

get_margin_ratio

証券の証拠金率を取得します。

result = await session.call_tool("get_margin_ratio", {"symbol": "HK.00700"})

市場情報関数

get_market_state

市場の状態を取得します。

result = await session.call_tool("get_market_state", {"market": "HK"})

利用可能な市場：「HK」、「US」、「SH」、「SZ」

get_security_info

証券情報を取得します。

result = await session.call_tool("get_security_info", {
    "market": "HK",
    "code": "00700"
})

get_security_list

市場の証券一覧を取得します。

result = await session.call_tool("get_security_list", {"market": "HK"})

get_stock_filter

条件に基づいて絞り込んだ株式一覧を取得します。

result = await session.call_tool("get_stock_filter", {
    "market": "HK.Motherboard",
    "base_filters": [{
        "field_name": 1,  # Price
        "filter_min": 10.0,
        "filter_max": 50.0,
        "sort_dir": 1  # Ascending
    }],
    "page": 1,
    "page_size": 50
})

時刻関数

get_current_time

現在のサーバー時刻を取得します。

result = await session.call_tool("get_current_time", {"random_string": "dummy"})

タイムスタンプ、書式設定済みの日時、日付、時刻、タイムゾーンを返します。