开放 API 中文 English

MCP 接入说明

让 Claude、Cursor 等 AI 助手直接查询你名下的设备:位置、轨迹、里程、报警事件,也能帮你设置电子围栏和报警开关。

服务地址https://xcslink.com/api/mcp
传输方式Streamable HTTP(仅 POST,不提供 SSE 流)
鉴权请求头 Authorization: Bearer 你的令牌
权限范围令牌所属账号能看到的设备,与小程序一致

推荐方式:一键授权

不用复制任何东西。在支持远程 MCP 的客户端里填上面的服务地址,客户端会自动打开授权页,你用数联在线账号登录、勾选要给的权限、点“允许”就连上了。Claude 桌面版、Claude.ai、ChatGPT、Cursor、VS Code、Gemini CLI 都走这条路。

授权页上有三项权限,可以只勾一部分:

权限能做什么
gps.read查看设备与位置、历史轨迹与里程、报警记录、电子围栏与报警设置
gps.write新增、修改、删除电子围栏,修改报警设置,创建位置分享链接
gps.command向真实设备发送远程指令
“向真实设备发送远程指令”是独立权限,不勾就给不了。 只给了查看权限的 AI,即使它自己想改围栏也会被服务端直接拒绝,这个判断在服务器上做,不依赖客户端自觉。

授权后访问令牌 1 小时过期,客户端会自动续期,你不用管。

随时撤销

网页端右上角自己的名称 → “对接令牌(MCP)”,弹窗下半部分列出所有已连接的 AI 客户端,可以单个撤销或全部撤销。撤销后该客户端立刻失去访问权限。

备选方式:长期令牌

客户端不支持一键授权,或者你在写脚本、做接口对接时用这条。已经在用长期令牌的客户端不受任何影响,继续用即可。

第一步:获取令牌

两个地方都能拿到同一类令牌,用哪个都行,取决于你平时用哪端。

网页端(推荐给没有微信小程序的用户)

  1. 用浏览器打开 https://xcslink.com/ 并登录。
  2. 点右上角自己的名称,展开菜单。
  3. 选“对接令牌(MCP)”,在弹窗里点“复制”。

微信小程序

  1. 打开本平台的微信小程序并登录。
  2. 点首页底部的“设置”,进入“我的”页面。
  3. 在顶部卡片里点“对接令牌(MCP) ****** 复制”,确认提示后,令牌就复制到了剪贴板。
令牌等同于你的登录凭证,请勿发给不信任的人。 在复制它的那一端重新登录或退出登录后,旧令牌立即失效,需要重新复制并更新到 AI 客户端里。 网页端和小程序各自独立:在网页端重新登录不会影响你从小程序复制的那一个,反过来也一样。

第二步:配置 AI 客户端

令牌只在你的浏览器里用于生成下面的配置文字,本页面不会把它发送到任何地方。

Claude Code

在终端执行(加 -s user 表示所有项目都可用):

claude mcp add --transport http -s user ulzx https://xcslink.com/api/mcp --header "Authorization: Bearer {{TOKEN}}"

执行 claude mcp list,看到 ulzx ... ✔ Connected 即配置成功。更换令牌时先执行 claude mcp remove ulzx -s user 再重新添加。

Cursor

编辑 ~/.cursor/mcp.json(全局)或项目下的 .cursor/mcp.json,写入:

{
  "mcpServers": {
    "ulzx": {
      "url": "https://xcslink.com/api/mcp",
      "headers": {
        "Authorization": "Bearer {{TOKEN}}"
      }
    }
  }
}

保存后在 Cursor 设置的 MCP 页面确认 ulzx 已启用。其他支持在配置文件里写 url 与 headers 的客户端,格式相同。

Claude 桌面版(以及只支持本地命令的客户端)

这类客户端不能直接填写请求头,需要借助开源工具 mcp-remote 转接。电脑上需先安装 Node.js 18 或更高版本。

打开配置文件:Claude 桌面版菜单“设置 → 开发者 → 编辑配置”,或直接编辑

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

写入以下内容后,完全退出并重新打开 Claude 桌面版:

{
  "mcpServers": {
    "ulzx": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://xcslink.com/api/mcp",
        "--header", "Authorization:${AUTH_HEADER}",
        "--transport", "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Bearer {{TOKEN}}"
      }
    }
  }
}

令牌放在 env 里、args 中不留空格,是为了避开 Windows 下参数里空格被拆开的问题。

其他支持远程 MCP 的客户端

在客户端的 MCP 服务器设置里按下表填写:

名称ulzx(可自定义)
类型Streamable HTTP(有的客户端叫“可流式传输的 HTTP”或 streamableHttp);不要选 SSE
地址https://xcslink.com/api/mcp
请求头名 Authorization,值 Bearer 你的令牌

如果客户端只能填写本地命令,按“Claude 桌面版”页签的方式用 mcp-remote 转接。

第三步:试一试

配置好后,直接用自然语言提问,AI 会自动调用合适的工具:

涉及“今天、昨天”等说法时,AI 会先调用 get_time_context 获取服务器时间,时间一律按北京时间理解。

工具一览

工具类型说明
get_time_context查询服务器当前时间,以及今天、昨天、本周起点的时间戳
list_devices查询账号下的设备列表
get_latest_info查询多台设备的最新位置、速度、电量、今日里程,可解析地址
device_latest_status查询单台设备最近通信与定位状态
get_history查询历史轨迹,单次最长 24 小时,点多时自动抽样
get_total_km查询一段时间内的行驶里程,单次最长 31 天
get_track_summary查询行程摘要:起终点、里程、最高速度
overview查询按日、月、年的统计:里程、使用时长、各类事件次数
event_stay查询停留记录
event_fence查询进出围栏记录
event_overspeed查询超速记录
event_acc查询ACC 状态切换记录
event_power_off查询断电、接电记录
event_low_power查询低电量记录
event_vibration查询震动记录
list_fences查询设备已设置的电子围栏及数量上限
get_alert_settings查询报警开关与超速阈值
list_expiring_devices查询即将到期或已到期的设备
list_device_commands查询某型号设备可用的远程指令
set_fence设置新增或修改圆形、多边形围栏
delete_fence设置删除围栏
set_alert_settings设置修改报警开关或超速阈值,只改你提到的项
create_share_link设置生成实时位置分享链接
send_device_command设置向设备下发低危指令,例如改定位频率、立即定位一次
prepare_device_command设备控制高危指令的第一步:回报设备名称、指令含义、可能影响,并给出一次性确认凭据
confirm_device_command设备控制高危指令的第二步:凭确认凭据真正下发

建议在 AI 客户端里保持“调用设置类工具前需确认”的默认行为。

注意事项

常见问题

提示 invalid session 或 401

令牌无效。通常是在复制它的那一端重新登录或退出过,请重新复制令牌并更新客户端配置。网页端、小程序、App 三种令牌都能用。

提示 insufficient_scope 或 403

授权时没勾这项权限。在网页端“对接令牌(MCP)”里撤销该客户端,然后在客户端中重新连接一次,勾上需要的权限即可。

客户端显示连接失败

确认地址是 https://xcslink.com/api/mcp(带 /api),类型选 Streamable HTTP 而不是 SSE,请求头的值以 Bearer 开头(后面有一个空格)。

偶尔出现 503

触发了频率限制,稍后重试即可。如果频繁出现,让 AI 逐个调用工具,不要一次并行很多个。

查不到轨迹

设备在该时间段内没有上报定位,或时间跨度超过 24 小时。可以先用 device_latest_status 看设备最后一次上报时间。

开发者:直接调用

协议为 JSON-RPC 2.0。工具业务错误在 result.isError=true 中返回,原因见 result.content[0].text。

curl -X POST https://xcslink.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'
curl -X POST https://xcslink.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tools/list 无需令牌,返回每个工具的完整参数说明。

OAuth 端点

按 MCP 授权规范实现,Authorization Code 加 PKCE,code_challenge_method 只接受 S256。未带凭证时 MCP 入口返回 HTTP 401 与 WWW-Authenticate,客户端据此自动发现下面这些地址。

用途地址
受保护资源元数据/.well-known/oauth-protected-resource/api/mcp
授权服务器元数据/.well-known/oauth-authorization-server
动态客户端注册POST /oauth/register
授权GET /oauth/authorize
换取令牌与刷新POST /oauth/token
撤销POST /oauth/revoke

同时支持动态客户端注册与 CIMD 两种免预注册方式。授权响应会带 iss,resource 参数按规范做 audience 校验。访问令牌 1 小时,刷新令牌 30 天且每次刷新滚动更新。

错误码

状态含义怎么处理
HTTP 401没带凭证,或 OAuth 令牌无效、已过期、已撤销按 WWW-Authenticate 里的地址走授权流程,或用刷新令牌续期
HTTP 403scope 不足,挑战头里的 scope 指明缺哪一项重新授权并勾上该权限
HTTP 503触发限流稍后重试,减少并行
JSON-RPC 401长期令牌无效重新复制令牌
JSON-RPC -32602工具名不存在先调 tools/list
result.isError=true工具业务错误原因见 result.content[0].text

MCP Integration Guide

Ask Claude, Cursor or any other MCP-capable assistant about your devices in plain language: where they are, where they have been, how far they drove, what alerts fired. They can also set geofences and alert switches for you.

Endpointhttps://xcslink.com/api/mcp
TransportStreamable HTTP (POST only, no SSE stream)
AuthHeader Authorization: Bearer YOUR_TOKEN
ScopeExactly the devices the token's account can see in the mini program

Recommended: one-click authorization

Nothing to copy. Put the endpoint above into any client that supports remote MCP, and the client opens an authorization page: sign in with your ShuLian Online account, tick the permissions you want to grant, press Allow. Claude Desktop, Claude.ai, ChatGPT, Cursor, VS Code and Gemini CLI all work this way.

The page offers three permissions and you may grant only some of them:

ScopeWhat it allows
gps.readView devices and positions, history tracks and mileage, alert records, geofences and alert settings
gps.writeCreate, modify and delete geofences, change alert settings, create location share links
gps.commandSend remote commands to real devices
Sending remote commands is a separate permission and is never implied by the other two. An assistant granted read access only is refused by the server if it tries to change a geofence. That check runs on the server, not in the client.

Access tokens expire after an hour and the client refreshes them for you.

Revoke at any time

In the web console click your name in the top-right corner, then “对接令牌(MCP)”. The lower half of the dialog lists every connected AI client; revoke one or all of them. Access stops immediately.

Alternative: long-lived token

Use this when your client has no one-click authorization, or when you are scripting against the API. Clients already using a long-lived token are unaffected and keep working.

Step 1: Get your token

Either place gives you the same kind of token; use whichever client you normally work in.

Web console (use this one if you do not have the WeChat mini program)

  1. Open https://xcslink.com/ in a browser and log in.
  2. Click your name in the top-right corner to open the menu.
  3. Choose “对接令牌(MCP)” (Integration Token) and click Copy in the dialog.

WeChat mini program

  1. Open our WeChat mini program and log in.
  2. Tap “设置” (Settings) at the bottom of the home page to open the “我的” (Me) page.
  3. In the top card, tap “对接令牌(MCP) ****** 复制” (integration token, copy) and confirm; the token is now on your clipboard.
This token is the same credential as your login, so treat it like a password. Logging in again or logging out in the client you copied it from invalidates it right away; copy the new one and update your AI client. The web console and the mini program keep separate sessions, so signing in again on one does not affect a token copied from the other.

Step 2: Configure your AI client

The token is only used inside your browser to render the text below. This page never sends it anywhere.

Claude Code

Run this in a terminal (-s user makes the server available in every project):

claude mcp add --transport http -s user ulzx https://xcslink.com/api/mcp --header "Authorization: Bearer {{TOKEN}}"

Then run claude mcp list. Seeing ulzx ... ✔ Connected means you are done. To swap in a new token, remove the server with claude mcp remove ulzx -s user and add it again.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "ulzx": {
      "url": "https://xcslink.com/api/mcp",
      "headers": {
        "Authorization": "Bearer {{TOKEN}}"
      }
    }
  }
}

Save the file, then check that ulzx is enabled on Cursor's MCP settings page. Any other client that takes url and headers in a config file uses the same shape.

Claude Desktop (and clients that only run local commands)

These clients cannot send a custom request header, so put the open-source bridge mcp-remote in front. It needs Node.js 18 or later.

Open the config file via “Settings → Developer → Edit Config” in Claude Desktop, or edit it directly:

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

Add the block below, then quit Claude Desktop completely and reopen it:

{
  "mcpServers": {
    "ulzx": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://xcslink.com/api/mcp",
        "--header", "Authorization:${AUTH_HEADER}",
        "--transport", "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Bearer {{TOKEN}}"
      }
    }
  }
}

The token sits in env and no argument contains a space, which keeps Windows from splitting the header apart.

Other clients with remote MCP support

Fill in the client's MCP server form like this:

Nameulzx (any name)
TypeStreamable HTTP (sometimes shown as streamableHttp); do not choose SSE
URLhttps://xcslink.com/api/mcp
HeaderName Authorization, value Bearer YOUR_TOKEN

If the client only takes a local command, bridge it with mcp-remote as shown in the Claude Desktop tab.

Step 3: Try it

Ask in plain language; the assistant picks the tools it needs:

For “today”, “yesterday” and the like, the assistant first calls get_time_context to get server time. Everything is Beijing time (UTC+8).

Tools

ToolAccessWhat it does
get_time_contextReadCurrent server time and timestamps for today, yesterday and this week
list_devicesReadDevices under the account
get_latest_infoReadLatest position, speed, battery and today's mileage of several devices, with optional address
device_latest_statusReadLatest communication and positioning status of one device
get_historyReadTrack points, up to 24 hours per call, sampled when there are many
get_total_kmReadMileage over a period, up to 31 days per call
get_track_summaryReadTrip summary: start, end, distance, top speed
overviewReadDaily, monthly or yearly statistics: mileage, usage time, event counts
event_stayReadStops
event_fenceReadGeofence entries and exits
event_overspeedReadSpeeding
event_accReadACC state changes
event_power_offReadPower cut and restore
event_low_powerReadLow battery
event_vibrationReadVibration
list_fencesReadGeofences on a device and the allowed maximum
get_alert_settingsReadAlarm switches and overspeed limit
list_expiring_devicesReadDevices expiring soon or already expired
list_device_commandsReadRemote commands available for a device model
set_fenceWriteCreate or modify a circular or polygon geofence
delete_fenceWriteDelete a geofence
set_alert_settingsWriteChange alarm switches or the overspeed limit; only what you mention
create_share_linkWriteCreate a live location sharing link
send_device_commandWriteSend a low-risk command, such as changing the tracking interval or requesting one fix
prepare_device_commandDevice controlFirst step for a high-risk command: reports the device name, what the command does and its impact, and returns a single-use confirmation id
confirm_device_commandDevice controlSecond step: sends the command, and only with a valid confirmation id

Keep your client's default of asking for confirmation before it runs anything in the Write group.

Notes

FAQ

“invalid session” or 401

The token is no longer valid, almost always because you logged in again or logged out in the client you copied it from. Copy the new token and update your client. Tokens from the web console, the mini program and the app all work.

“insufficient_scope” or 403

That permission was not granted. Revoke the client under “对接令牌(MCP)” in the web console, connect again from the client and tick the permission you need.

The client cannot connect

Check three things: the URL is https://xcslink.com/api/mcp (note the /api), the type is Streamable HTTP and not SSE, and the header value starts with Bearer followed by a space.

Occasional 503

You hit the rate limit. Retry in a moment; if it keeps happening, ask the AI to call tools one at a time instead of firing many in parallel.

No track data

Either the device reported no positions in that window, or the window is longer than 24 hours. Check the last report time with device_latest_status first.

Developers: raw calls

The protocol is JSON-RPC 2.0. Tool-level errors come back as result.isError=true, with the reason in result.content[0].text.

curl -X POST https://xcslink.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'
curl -X POST https://xcslink.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tools/list needs no token and returns the full parameter schema of every tool. The tool descriptions themselves are in Chinese; mainstream models read them without trouble and will still answer you in English.

OAuth endpoints

Implemented per the MCP authorization spec: Authorization Code with PKCE, and code_challenge_method must be S256. Without credentials the MCP endpoint answers HTTP 401 with a WWW-Authenticate challenge, which is how clients discover the addresses below.

PurposeAddress
Protected resource metadata/.well-known/oauth-protected-resource/api/mcp
Authorization server metadata/.well-known/oauth-authorization-server
Dynamic client registrationPOST /oauth/register
AuthorizationGET /oauth/authorize
Token and refreshPOST /oauth/token
RevocationPOST /oauth/revoke

Both dynamic client registration and client ID metadata documents are supported, so no manual pre-registration is required. Authorization responses carry iss, and the resource parameter is validated as the token audience. Access tokens last one hour; refresh tokens last 30 days and rotate on every use.

Error codes

StatusMeaningWhat to do
HTTP 401No credentials, or the OAuth token is invalid, expired or revokedFollow the address in WWW-Authenticate to authorize, or refresh the token
HTTP 403Insufficient scope; the challenge names the missing oneAuthorize again and grant that permission
HTTP 503Rate limitedRetry shortly and reduce parallelism
JSON-RPC 401The long-lived token is not validCopy a fresh token
JSON-RPC -32602Unknown tool nameCall tools/list first
result.isError=trueTool-level errorReason is in result.content[0].text