Files

T

Hermes Skills Manager 6770bc9b9d Initial commit: Hermes Agent skills collection

- Trading skills (OKX, dividend, lottery, quantitative)
- Creative skills (ASCII art, diagrams, video)
- Development skills (GitHub, debugging, TDD)
- Research skills (arXiv, blog monitoring)
- Productivity skills (email, documents, notes)
- MCP integration skills
- Custom user skills

2026-07-05 02:31:15 -04:00

4.0 KiB

Raw Blame History

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. Try a VPN/WireGuard exit to Hong Kong or overseas. Use the WireGuard on/off scripts (wg-on, wg-off) if available.
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 VPN.

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.0 KiB Raw Blame History Unescape Escape