mike
657dc41c46
- OKX交易自动化 (okx-auto-position, okx-crypto, okx-exchange) - 交易信号处理 (signal-confirmation-templates, trading-signal-aggregator) - 量化因子挖掘 (quant-factor-mining) - 长桥集成 (longbridge-cli, longbridge-python-sdk) - 六合彩分析 (lottery-hk) - 股息投资 (dividend-investing, dividend-scanner) - 日内交易 (intraday-trading) - 同花顺 (tonghuashun)
118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
# 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:
|
||
|
||
```yaml
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
pip install mcp
|
||
# or
|
||
uv pip install mcp
|
||
```
|
||
|
||
Without it, MCP support is silently disabled and no MCP servers connect.
|
||
|
||
## See Also
|
||
|
||
- `native-mcp` skill: general MCP client configuration for Hermes
|
||
- `longbridge-cli` skill: CLI-based LongPort access (fallback if MCP is unavailable)
|
||
- `longbridge-python-sdk` skill: Python SDK-based LongPort access
|