OneMap MCP 服务器

将 OneMap 车队追踪系统开放给 Claude、ChatGPT 以及任何其他 MCP 客户端，让用户可以用自然语言提问，而无需操作报表界面：

卡车 12 现在在哪里？ 上周配送车队总共跑了多少公里？ 把周一至周五的厢式货车行程报表发到我的邮箱。 昨晚有哪些车辆触发了警报？

32 个工具覆盖完整的 API 面——设备、位置、全部七种报表类型、地理围栏、驾驶员、维护、通知、日历、用户、权限以及设备指令下发。

快速开始

npm install && npm run build

复制 .env.example 为 .env，填写你的服务器地址和令牌：

cp .env.example .env

验证连接是否正常：

npm test

Related MCP server: OpenStreetMap MCP Server

身份认证

插件的权限永远不会超过其背后 OneMap 账号的权限。该用户通过 Web 界面能看到的设备、分组和报表，也就是模型能访问的全部内容——OneMap 自身的权限系统负责执行访问控制，这里没有另外一套独立的权限模型需要同步维护。

两种方式，在 .env 中配置：

• ONEMAP_TOKEN（推荐）——为该账号签发的一个 API 令牌，以 Bearer 令牌形式发送。无需修改密码即可吊销。

• ONEMAP_EMAIL + ONEMAP_PASSWORD——基本认证。可用，但密码会以明文形式保存在磁盘上；仅用于快速上手。

连接客户端

Claude Desktop / Claude Code（stdio）

在 claude_desktop_config.json（或 Claude Code 的 .mcp.json）中添加：

{
  "mcpServers": {
    "onemap8": {
      "command": "node",
      "args": ["/absolute/path/to/ai-plugin/dist/stdio.js"],
      "env": {
        "ONEMAP_URL": "https://mcp.onemap8.com/api",
        "ONEMAP_TOKEN": "your-token-here",
        "ONEMAP_ALLOW_COMMANDS": "false"
      }
    }
  }
}

远程 / ChatGPT 连接（HTTP）

npm run start:http

在 POST /mcp 上提供 Streamable HTTP 服务（健康检查位于 /health）。它采用无状态运行——每个请求对应一个全新的服务器实例，请求之间不共享任何数据——因此单个部署即可服务大量用户。

当 ONEMAP_HTTP_PASSTHROUGH_AUTH=true（默认值）时，每个请求的 Authorization: Bearer <token> 请求头会提供该调用者自己的 OneMap 令牌，因此每个用户都只能在自己的权限范围内操作，而不是共用一个服务账号。

在公网暴露之前：

• 请在前方配置 TLS 终止——令牌会随请求头传输。

• 如果客户端来自浏览器，请设置 ONEMAP_ALLOWED_ORIGINS；未列入白名单的来源将被拒绝。

• 本项目不实现 OAuth。要么在前面加一个实现了 OAuth 的网关，要么给每个用户一个 OneMap API 令牌，让他们粘贴到自己的客户端中。

安全护栏

账号自身的权限才是真正的安全边界。以下这些开关是第二道防线——它们限制的是模型能对账号做什么，这与账号本身被允许做什么是两个不同的问题。

另外还有两个工具需要显式传入 confirm: true 参数（在上述开关之外）：

onemap_send_command 和 onemap_delete_positions。

具体到设备指令： onemap_send_command 会触及物理硬件——发动机锁、门锁、继电器。启用它意味着语言模型只需一次工具调用就能让车辆熄火。默认开启是因为你要求完整的工具面，但如果有除你之外的任何用户能访问该部署，请认真考虑设置 ONEMAP_ALLOW_COMMANDS=false，把指令下发留给操作人员自己的界面。

定时报表

OneMap API 没有定时报表的端点。 它只能按需发送一次邮件报表——调用 onemap_report 并设置 delivery: "mail" 会请求 /reports/{type}/mail，服务器将电子表格以邮件形式发送给账号所有者。

要实现周期性报表，需要由外部调度器反复调用同一个接口：

任何对业务有重要影响的场景，请使用第一种方案。schedule_recurring_report 提示词模板会引导你完成选择报表和参数、先运行一次验证输出、然后再安排定期执行的全过程。

n8n 中的大致配置为：Schedule Trigger → HTTP Request 请求 GET {ONEMAP_URL}/reports/trips/mail，携带 deviceId、from、to 参数以及 Authorization: Bearer 请求头。

工具参考

车队状态 — onemap_list_devices、onemap_get_device、onemap_list_groups、onemap_live_positions、onemap_position_history、onemap_get_event、onemap_geocode、onemap_whoami、onemap_statistics、onemap_audit_log

报表 — onemap_report（路线、事件、行程、停靠、汇总、地理围栏、综合报表 × json/xlsx/mail 格式）、onemap_report_devices_xlsx

配置管理 — onemap_geofences、onemap_drivers、onemap_maintenance、onemap_calendars、onemap_notifications、onemap_computed_attributes、onemap_orders（每个工具都接受 action 参数：list/get/create/update/delete）

指令下发 — onemap_command_types、onemap_saved_commands、onemap_send_command

系统管理 — onemap_manage_device、onemap_manage_group、onemap_users、onemap_permissions、onemap_share、onemap_send_notification、onemap_session_token、onemap_stream_url、onemap_server_settings、onemap_delete_positions

设计说明

扩展本项目时需要了解的两个设计决策：

• 名称在服务端解析为 ID。 工具接受 deviceNames: ["Truck 12"] 这样的参数，并在服务端查找对应的 ID，因为用户习惯说名称，而模型只能猜测 ID。遇到重名时，工具会拒绝解析并列出所有候选，而不是随意选一个——选错车辆导致的静默错误比直接失败更糟糕。

• 一个报表工具，而不是八个。 七个报表端点之间只差路径中的一个字段，因此合并为一个带 report 判别参数的工具。更短的工具列表能显著提升模型的选型准确率；同样的理由也适用于将实体 CRUD 合并为带 action 判别参数的工具。

命名时间段（如 period: "lastWeek"）同样在服务端解析——一周从周一开始——因为让模型自己计算日期很容易产生难以察觉的错误。

在修改这些代码路径之前，有两个 API 的怪癖值得了解，它们都是通过对真实服务器进行测试发现的，而不是靠阅读规格文档：

• GET /session 会忽略 Authorization: Bearer 请求头。 它报告的是 cookie 会话的信息，在没有会话时返回 404。使用令牌的客户端必须通过 ?token= 参数传递，而 OneMapClient.getSessionUser() 仅在回退时才会这样做——这会把凭据写入服务器的访问日志，因此绝不会作为首选方案。

• /positions 上的 id 参数指的是位置 ID，而不是设备 ID，而且 deviceId 必须配合显式的 from/to 参数使用。因此"最新位置"的正确做法是不带任何参数调用 GET /positions，然后在客户端过滤。如果把设备 ID 当作 id 传入，服务器会返回 500（NullPointerException）。

开发

npm run dev        # tsc --watch
npm test           # build + smoke tests against a mock API
npm run inspect    # MCP Inspector against the stdio server

test/smoke.mjs 会启动一个模拟的 OneMap API，并通过内存中的 MCP 客户端驱动真实服务器，覆盖名称解析、时间段展开、数组查询编码、邮件发送以及每一项安全护栏。