LongPort MCP Integration

LongPort offers an MCP (Model Context Protocol) server as an alternative to the longbridge CLI and Python SDK. This is useful for AI agents that need native MCP tool discovery rather than custom CLI/SDK integration.

Architecture

LongPort's MCP service uses a two-endpoint architecture:

Endpoint	URL	Purpose
Auth endpoint	`https://mcp.longport.cn/agent`	Single tool: `authenticate` — exchanges an auth code for an access token
Main service	`https://mcp.longport.cn`	All LongPort data tools (quotes, orders, positions, etc.) — requires Bearer token

The auth endpoint exists only for credential exchange and is NOT a permanent MCP service; disconnect it after obtaining the token.

Auth Flow (Two Steps)

Step 1: Get Access Token

Connect to https://mcp.longport.cn/agent and call the authenticate tool:

POST https://mcp.longport.cn/agent
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "authenticate",
    "arguments": {
      "code": "<one-time auth code from LongPort App>"
    }
  },
  "id": 1
}

Response includes the access token and the exact config command for the main service (e.g., headers with Authorization: Bearer <token>).

Auth codes: Single-use, valid for ~10 minutes. Generate from LongPort App → Open API → MCP.

Step 2: Connect Main Service

Once you have the token, connect to the main MCP service with the Bearer token as a request header:

# In Hermes config.yaml under mcp_servers:
mcp_servers:
  longport:
    url: "https://mcp.longport.cn"
    headers:
      Authorization: "Bearer <your_access_token>"
    timeout: 180
    connect_timeout: 60

After adding the config, restart Hermes Agent. All LongPort MCP tools will auto-discover and become available as mcp_longport_* tools.

The temp auth endpoint (/agent) connection can be removed after token exchange — it's not needed for regular use.

Tool Availability

Once connected to the main service, available tools include:

Quote tools: real-time quotes, candlesticks, calc_indexes
Account tools: positions, balance, orders
Trade tools: buy, sell, cancel orders
Watchlist tools: list groups, securities
Static info: EPS, BPS, shares outstanding

(The tool names auto-prefix as mcp_longport_<tool_name> in Hermes.)

Token Management

Expiry: LongPort access tokens expire after ~180 days (same as API tokens).
Refresh: Generate a new auth code from the LongPort App and repeat the two-step flow.
401003: Token expired — re-authenticate from scratch.
401004: Token invalid/truncated — verify the token JWT structure is intact.

Troubleshooting

DNS / Connectivity

The LongPort MCP servers live at mcp.longport.cn. If this domain doesn't resolve:

dig mcp.longport.cn
curl -s -o /dev/null -w "%{http_code}" https://mcp.longport.cn

China mainland access: DNS may be blocked or restricted. Use mihomo (Clash) HK exit — proxychains4 -f ~/.proxychains/proxychains.conf works for CLI; for Python SDK / MCP-from-agent traffic, set HTTP_PROXY=http://127.0.0.1:7890 before launching.
❌ DO NOT suggest WireGuard for this account — user explicitly banned WG (see main SKILL.md WireGuard: BANNED section). All WG scripts were deleted after a 2026-07-15 incident left 0.0.0.0/1 + 128.0.0.0/1 residual routes that broke all network. Suggesting WG again will get you corrected.
Timeout: Increase connect_timeout to 60–120s. LongPort MCP can be slow to respond on first connection.
ERR_NAME_NOT_RESOLVED: Domain unreachable from current network. Try alternate DNS (8.8.8.8) or check mihomo node status.

Auth Code Expiry

Auth codes are single-use and expire ~10 minutes after generation. If you get an error calling authenticate:

Generate a fresh code from the LongPort App
Retry step 1 immediately

MCP SDK Requirement

Hermes' native MCP client requires the mcp Python package:

pip install mcp
# or
uv pip install mcp

Without it, MCP support is silently disabled and no MCP servers connect.

4.4 KiB Raw Blame History Unescape Escape