Skip to main content
Glama
dekozh
RockFlow-AI

broker-mcp-demo

by RockFlow-AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Broker MCP Demo

基于 FastMCP 的券商 MCP Server Demo（Python 版）， 做了两点简化：

  • 鉴权用静态 API key（Authorization: Bearer <api-key>），不走 OAuth；

  • 不内置任何真实服务地址：下游券商后端地址由使用者通过环境变量自行配置， 未配置时各工具返回内置示例数据（响应带 "mock": true 标记），开箱即可体验。

架构

┌─────────────┐  Bearer <api-key>  ┌────────────────────┐   HTTP   ┌──────────────┐
│  MCP Client │───────────────────▶│  Broker MCP Demo   │─────────▶│  券商后端服务  │
│  (Claude…)  │◀───────────────────│  (API key 校验)     │◀─────────│ （自行配置）   │
└─────────────┘                    └────────────────────┘          └──────────────┘

请求流程：

  1. 客户端带 Authorization: Bearer <api-key> 请求 POST /mcp；如需按用户维度 执行，同时在请求头 X-User-Id 中原样透传券商体系内的用户 ID。

  2. 服务端将 key 与 BROKER_MCP_API_KEYS 中配置的逐一比对，命中放行、否则 401。

  3. 工具调用被代理到 BROKER_MCP_BACKEND_BASE_URL 指向的券商后端； 未配置时返回内置示例数据。

调用方身份由两层组成：API key 解析出的 client_id（哪家券商）+ 请求头 X-User-Id 透传的用户 ID（该券商体系内的哪个用户）。持仓、资产、订单、下单等 工具会把 X-User-Id 原样透传给券商后端，按用户维度执行；未携带时该 header 不下发（如仅体验行情类工具）。

Related MCP server: Open Stocks MCP

工具

共 10 个示例工具，覆盖行情、持仓 / 订单、交易、知识库四类。下游接口路径均为示意， 接入真实后端时按约定改 tools/ 里的 path 即可。

行情（market.py）

工具

参数

说明

search_ticker

keyword

按公司名 / 代码搜索标的，解析出 market + symbol

get_latest_quote

market, symbol

查询标的最新行情

get_chart

market, symbol, span=1month

历史 K 线；span 支持 1day / 1week / 1month / 1year / 5year

持仓 / 资产 / 订单（portfolio.py）

工具

参数

说明

get_positions

—

当前持仓列表（含盈亏）

get_assets

—

账户资产（现金、市值、总资产等）

get_orders

status=OPEN, limit=20

订单列表；status 支持 OPEN / FILLED / CANCELLED / ALL

get_order

order_id

单个订单详情

cancel_order

order_id

撤销一个未成交订单

交易（trade.py）

工具

参数

说明

create_order

symbol, market, side, order_type, quantity, price?, validity

创建（提交）一个交易订单

  • order_type：MARKET_ORDER（市价）/ LIMIT_ORDER（限价，需带 price）。

  • side：BUY / SELL；validity：GOOD_FOR_DAY / GOOD_TILL_CANCELLED。

知识库（knowledge.py）

工具

参数

说明

search_knowledge_base

query, language=zh-Hans, top=10

搜索平台知识库（开户、出入金、交易规则等 QA）

  • language：zh-Hans / zh-Hant / en；top 范围 3~20。

  • 真实项目通常由后端做向量检索 + 语义排序（如 Azure Cognitive Search、 Elasticsearch、Milvus 等），本 demo 不绑定具体实现。

每个工具都套了 decorators.py 的 log_tool 装饰器，统一打印调用方（API key 对应的 client_id）、入参与耗时日志。新增工具时 在对应模块 register(mcp) 内用 @mcp.tool + @log_tool 声明，并在 tools/__init__.py 的 register_tools() 注册。

运行

pip install -r requirements.txt

cp .env.example .env   # 按需修改 API key、后端地址
python -m broker_mcp_demo

默认监听 0.0.0.0:8000，MCP 端点为 /mcp，健康检查为 /health。

配置

全部通过环境变量（前缀 BROKER_MCP_）或 .env 注入，参考 .env.example：

变量

说明

BROKER_MCP_API_KEYS

必填（除非关闭鉴权）。逗号分隔，每条为 key 或 key:client_id，如 demo-key-1:alice,demo-key-2:bob

BROKER_MCP_BACKEND_BASE_URL

下游券商后端根地址（demo 不内置真实地址，自行配置）；留空时工具返回示例数据

BROKER_MCP_HOST / BROKER_MCP_PORT

监听地址 / 端口，默认 0.0.0.0:8000

BROKER_MCP_TRANSPORT

http（默认）或 stdio

BROKER_MCP_AUTH_DISABLED

true 关闭鉴权，仅本地调试用

BROKER_MCP_BACKEND_TIMEOUT

下游请求超时秒数，默认 30

客户端接入

以 Claude Code 为例（HTTP 模式 + API key）：

claude mcp add --transport http broker-demo http://localhost:8000/mcp \
  --header "Authorization: Bearer demo-key-1"

或在 MCP 客户端的 JSON 配置中：

{
  "mcpServers": {
    "broker-demo": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer demo-key-1"
      }
    }
  }
}

stdio 模式

用于本地调试，走 stdin/stdout 且不启用鉴权：

BROKER_MCP_TRANSPORT=stdio python -m broker_mcp_demo

目录结构

src/broker_mcp_demo/
├── __main__.py     入口（python -m broker_mcp_demo）
├── config.py       环境变量 / .env 配置读取
├── auth.py         API key 鉴权（ApiKeyVerifier）
├── identity.py     解析调用方身份（client_id + X-User-Id）
├── backend.py      下游后端 HTTP 调用封装（未配置地址时回退示例数据）
├── server.py       FastMCP 实例装配
└── tools/          MCP 工具
    ├── __init__.py     register_tools() 注册入口
    ├── decorators.py   log_tool 计时日志装饰器
    ├── market.py       行情
    ├── portfolio.py    持仓 / 资产 / 订单
    ├── trade.py        下单
    └── knowledge.py    平台知识库搜索

License

Apache-2.0

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers