tl-openmeter-api-mcp-server

用途

tl-openmeter-api-mcp-server 是一个 MCP（Model Context Protocol）服务器，用于与本地的 OpenMeter 实例交互。它让 Cursor、Claude 等 AI 助手能够实际调用 OpenMeter API，而不仅仅是提供文档参考：列出计量表、管理客户与订阅、查询用量、摄取测试事件、检查 OpenMeter 是否运行等。

官方将其定位为 tl-agent-skills 套件的一部分，与另外两个技能配合：

tl-openmeter-api：REST API 参考（知识）
tl-openmeter-local-dev：本地开发环境搭建（Docker、ngrok、Stripe App、webhooks）
tl-openmeter-api-mcp-server：本技能，用于从 Cursor 调用 OpenMeter

适用场景

当需要让智能体真正调用 OpenMeter API（而不只是提供文档）时使用，例如：

“列出我的 OpenMeter 计量表”
“在 OpenMeter 中创建客户”
“查询该计量表的用量”
“摄取一个测试事件”
“检查 OpenMeter 是否在运行”

前置条件

Node.js 18+
正在运行的 OpenMeter 实例（例如 Docker，默认 http://localhost:8888）

安装

Step 1：构建服务器。在技能目录执行：

npm install
npm run build

Step 2：在 Cursor MCP 配置中注册。添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "OpenMeter": {
      "command": "node",
      "args": ["C:\\Users\\Todd\\.cursor\\skills\\@tl-agent-skills\\skills\\tl-openmeter-api-mcp-server\\dist\\index.js"],
      "env": {
        "OPENMETER_URL": "http://localhost:8888",
        "OPENMETER_API_KEY": ""
      }
    }
  }
}

需要根据实际安装位置调整路径。

Step 3：重启 Cursor。Cursor 需要重启才能加载 MCP 配置的更改。

环境变量

变量	默认值	说明
OPENMETER_URL	http://localhost:8888	OpenMeter API 的基础 URL
OPENMETER_API_KEY	（无）	可选的 Bearer token 用于认证

本地开发通常不需要设置 OPENMETER_API_KEY。

可用工具

工具	用途
openmeter_list_meters	GET /api/v1/meters
openmeter_get_meter	GET /api/v1/meters/{idOrSlug}
openmeter_query_usage	GET /api/v1/meters/{idOrSlug}/query
openmeter_list_customers	GET /api/v1/customers（分页）
openmeter_get_customer	GET /api/v1/customers/{idOrKey}
openmeter_create_customer	POST /api/v1/customers
openmeter_list_subscriptions	列出订阅（可选 customerId）
openmeter_create_subscription	POST /api/v1/subscriptions
openmeter_cancel_subscription	POST /api/v1/subscriptions/{id}/cancel
openmeter_list_plans	GET /api/v1/plans
openmeter_list_features	GET /api/v1/features
openmeter_get_entitlements	GET /api/v1/customers/{id}/entitlements
openmeter_ingest_event	POST /api/v1/events（CloudEvents JSON）
openmeter_list_apps	GET /api/v1/apps
openmeter_list_billing_profiles	GET /api/v1/billing/profiles
openmeter_check_status	验证与 OpenMeter 的连接

资源

OpenMeter 速查参考 — 来自 tl-openmeter-api 技能的 Markdown
OpenMeter 规格说明 — 纯文本，包含规格 URL 和已配置的基础 URL

验证

启动 OpenMeter（例如 docker compose up 或你的技术栈）
确保 OpenMeter MCP 服务器已在 Cursor 中配置并启用
在对话中询问：“Check the OpenMeter status”或“List OpenMeter meters”
智能体应调用 openmeter_check_status 或 openmeter_list_meters 并返回结果

错误（例如连接被拒绝）会作为工具结果返回，以便智能体进行报告。

故障排查

问题	原因	修复
工具不可用	服务器未在 mcp.json 中	添加配置项，重启 Cursor
连接被拒绝	OpenMeter 未运行	启动 OpenMeter（docker compose up）
401 Unauthorized	缺少 API key	在环境变量中设置 OPENMETER_API_KEY
服务器无法启动	未构建	在技能目录执行 npm run build

MCP 设计原则

资料引用了 anthropics/skills/mcp-builder 的设计原则。

工具命名：使用一致、面向动作的前缀。

openmeter_list_meters ✓（list 动作）
openmeter_get_customer ✓（get 动作）
openmeter_create_subscription ✓（create 动作）
meters ✗（无动作前缀）

API 覆盖 vs 工作流工具：在全面的 API 端点覆盖和专门的工作流工具之间取得平衡。全面覆盖让智能体能够灵活组合操作；工作流工具（例如 openmeter_provision_customer）将多个调用组合用于常见任务。不确定时，优先保证全面的 API 覆盖。

可操作的错误消息：错误消息应引导智能体找到解决方案，例如给出客户未找到并提示使用 openmeter_list_customers 查找有效 ID。

分页：所有列表操作支持基于游标的分页，参数包括 page 和 pageSize（默认 100，最大 1000），响应包含 items、page、pageSize、totalCount。

工具实现与批量操作

资料给出了工具注册的示例代码，使用 server.registerTool 注册工具，包含 name、description、inputSchema（使用 zod）和 async handler。批量操作部分给出了 openmeter_batch_ingest 的示例，用于在单个请求中摄取多个 CloudEvents，客户端将事件映射为 CloudEvents 格式（specversion、id、source、type、subject、time、data），并以 application/cloudevents-batch+json 发送。

工具注解

可使用注解标记工具行为：readOnlyHint（是否只读）、destructiveHint（是否破坏性删除）、idempotentHint（是否幂等）、openWorldHint（是否与外部服务交互）。资料给出了 openmeter_create_customer 与 openmeter_list_meters 的注解示例。

测试

MCP Inspector：使用 npx @modelcontextprotocol/inspector 交互式测试工具
Mock 服务器：可通过 createMockMcpServer 创建，为工具（如 openmeter_list_meters）提供模拟返回值
集成测试模式：资料给出了测试用例示例，例如“从运行中的 OpenMeter 列出计量表”以及“对无效客户返回可操作的错误”（断言错误信息包含 openmeter_list_customers）

参考资料

资料列出的参考资料包括：anthropics/skills/mcp-builder（MCP 服务器开发指南）、MCP Specification（协议规范）、MCP TypeScript SDK（SDK 参考）、OpenMeter API（API 端点），以及 MCP Server Examples、MCP Inspector、MCP Best Practices。

限制

资料未提供关于收费、价格、平台覆盖范围或性能指标的说明，这些信息暂未提供。