Skip to main content
Glama
deenesjakoruzh
tejasghalsasi

helcim-mcp

by tejasghalsasi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

helcim-mcp

非官方 Helcim API 社区 MCP 服务器和开发者工具包。 安全、类型化、对代理友好，且默认只读。 与 Helcim Inc. 无关联，未受其赞助、维护或认可。

helcim-mcp 是一个生产级、TypeScript 单体仓库，让 AI 代理（以及人类）能够安全、轻松地使用 Helcim 支付平台。它提供三样东西：

  1. @helcim-mcp/server — 一个 MCP 服务器，暴露只读的 Helcim 工具（客户、发票、银行卡交易、银行卡批次、定期支付计划、订阅、连接测试）。

  2. @helcim-mcp/core — 一个类型化、感知幂等性的 Helcim API 客户端，具备规范化错误、限流处理和密钥脱敏功能。

  3. @helcim-mcp/webhooks — 一个独立的 Helcim Webhook 验证器（HMAC-SHA256 签名验证、时间戳校验、重放保护、类型化事件）。

为什么要使用它？

  • 你希望 AI 代理回答关于你的 Helcim 数据的问题 — “哪些发票尚未结清？”、“显示最近的银行卡交易”、“查找此发票对应的客户”、“哪些订阅需要关注？” — 而绝无资金变动风险。

  • 你想要一个简洁、类型化的 Helcim 客户端，替你处理 API 的各种怪癖（HTTP 200 ≠ 成功、errors 对象结构、幂等性、限流、分页），无需自己动手。

  • 你想要安全地验证 Helcim Webhook，使用恒定时间签名比较和重放保护，无需重新发明 HMAC 方案。

MCP 服务器默认只读。它在物理上无法创建、更新、删除或转移资金——不存在此类工具。即使拥有完整处理权限的令牌，也无法通过此服务器触发资金变动。

Related MCP server: HighLevel MCP Server

快速开始

1. 获取 Helcim API 令牌

登录你的 Helcim 账户（或开发者测试账户），前往 所有工具 → 集成 → API 访问配置，创建一个配置。对于只读用途，请将 常规：读取、设置：读取 和 交易处理：无。

2. 运行 MCP 服务器

# From source
git clone https://github.com/tejasghalsasi/helcim-mcp.git
cd helcim-mcp
pnpm install
pnpm rebuild esbuild   # required: pnpm 11 blocks esbuild's postinstall by default
pnpm build

# Set your token (never commit it)
export HELCIM_API_TOKEN="your_token_here"

# Run over stdio
node packages/mcp/dist/index.js

3. 将其连接到 MCP 客户端

将此添加到你的 MCP 客户端配置中（例如 Claude Desktop、Cursor 或任何 MCP 客户端）：

{
  "mcpServers": {
    "helcim": {
      "command": "node",
      "args": ["/absolute/path/to/helcim-mcp/packages/mcp/dist/index.js"],
      "env": {
        "HELCIM_API_TOKEN": "your_token_here"
      }
    }
  }
}

4. 向你的代理提问

连接后，你的代理可以调用如下工具：

  • connection_test — 确认令牌可用。

  • 使用 status: "DUE" 调用 list_invoices — “哪些发票尚未结清？”

  • list_card_transactions — “显示最近的银行卡交易。”

  • get_customer — “查找此发票对应的客户。”

  • 使用 hasFailedPayments: true 调用 list_subscriptions — “哪些订阅需要关注？”

只读模式的工作原理

  • MCP 服务器仅暴露只读工具。不存在支付、退款、捕获、撤销、提现、结算或删除工具。

  • 核心客户端在 v1 中不暴露任何写入方法。

  • 如果未来版本添加写入功能，将需要显式的 HELCIM_ENABLE_WRITES=true 环境变量以及一个独立的用于资金变动的高风险功能开关，并附有完善的文档和测试。

  • HTTP 200 不被视为成功。Helcim 明确警告，200 响应并不意味着请求的操作已成功；客户端会将响应体中的 errors 作为类型化错误呈现。

凭据如何受到保护

  • API 令牌仅从 HELCIM_API_TOKEN 环境变量中读取。绝不硬编码、绝不提交、绝不记录日志。

  • 所有日志行和错误消息都经过 redact() 处理。类似令牌的字符串、卡号和 F6L4 值会被替换为 <redacted-...>。

  • 令牌永远不会暴露给模型。MCP 服务器仅返回脱敏数据和类型化错误代码。

  • 有关完整的安全模型，请参阅 SECURITY.md。

架构

flowchart LR
    subgraph Client["MCP Client (LLM)"]
        A[Agent]
    end

    subgraph Server["@helcim-mcp/server"]
        M[MCP Server<br/>stdio transport]
        T[Read-only tools<br/>13 tools]
    end

    subgraph Core["@helcim-mcp/core"]
        C[HelcimClient]
        H[HelcimHttpClient<br/>auth, idempotency,<br/>rate-limit, redaction]
        E[Normalized errors]
    end

    subgraph Webhooks["@helcim-mcp/webhooks"]
        W[HelcimWebhookVerifier<br/>HMAC-SHA256, replay protection]
    end

    subgraph Helcim["Helcim API"]
        API[api.helcim.com/v2]
    end

    A -->|JSON-RPC over stdio| M
    M --> T
    T --> C
    C --> H
    H -->|HTTPS + api-token| API
    W -.->|verifies signed events| API

单体仓库布局：

helcim-mcp/
├── packages/
│   ├── core/       # Typed Helcim API client (read-safe)
│   ├── mcp/        # MCP server (read-only tools)
│   ├── webhooks/   # Webhook verifier
│   └── fixtures/   # Deterministic mock responses + test vectors
├── examples/       # Copy-paste usage examples
├── docs/           # Architecture, env reference, troubleshooting
└── scripts/        # Smoke test, CI helpers

示例交互

代理： “目前有哪些发票尚未结清？”

list_invoices(status: "DUE")
→ { count: 2, invoices: [
    { invoiceId: 28658838, invoiceNumber: "INV1000", status: "DUE", currency: "CAD", customerId: 2488717 },
    { invoiceId: 28658839, invoiceNumber: "INV1001", status: "DUE", currency: "USD", customerId: 2488718 }
  ] }

代理： “显示最近的银行卡交易。”

list_card_transactions(limit: 5)
→ { count: 2, transactions: [
    { transactionId: 25557533, status: "APPROVED", type: "purchase", amount: 100.99, currency: "CAD", cardType: "MC", customerCode: "CST1000" },
    { transactionId: 25557534, status: "DECLINED", type: "purchase", amount: 250.00, currency: "CAD", cardType: "VI", customerCode: "CST1001" }
  ] }

代理： “查找与此发票关联的客户。”

get_invoice(invoiceId: 28658838) → { customerId: 2488717, ... }
get_customer(customerId: 2488717) → { customerCode: "CST1000", businessName: "Acme Widgets Ltd", ... }

代理： “显示需要关注的订阅。”

list_subscriptions(hasFailedPayments: true)
→ { count: 1, subscriptions: [ { id: 42, status: "ACTIVE", hasFailedPayments: true, customerCode: "CST1000", ... } ] }

代理： “为交易 25557533 处理退款。”

→ Error: Unknown tool: process_refund

代理无法转移资金。不存在此类工具。

Webhook 验证

import { HelcimWebhookVerifier } from '@helcim-mcp/webhooks';

const verifier = new HelcimWebhookVerifier(process.env.HELCIM_VERIFIER_TOKEN!);

// In your webhook handler (e.g. Next.js route handler):
export async function POST(req: Request) {
  const body = await req.text();
  const headers = Object.fromEntries(req.headers.entries());
  try {
    const verified = verifier.verify(headers, body);
    // verified.event.type === 'cardTransaction' | 'terminalCancel'
    return new Response('ok', { status: 200 });
  } catch (err) {
    return new Response('invalid signature', { status: 401 });
  }
}

有关完整的 Next.js 示例，请参阅 examples/webhook-nextjs.md。

环境变量

变量

是否必需

说明

HELCIM_API_TOKEN

是（用于服务器）

你的 Helcim API 令牌。

HELCIM_BASE_URL

否

覆盖基础 URL（默认 https://api.helcim.com/v2）。

HELCIM_DEBUG

否

设为 true 以启用脱敏请求日志记录。

HELCIM_TIMEOUT_MS

否

请求超时时间（毫秒，默认 15000）。

HELCIM_VERIFIER_TOKEN

用于 Webhook

你的 Helcim Webhook 验证器令牌。

有关完整参考，请参阅 docs/environment.md。

开发

pnpm install
pnpm rebuild esbuild  # pnpm 11 blocks esbuild's postinstall by default
pnpm build        # build all packages
pnpm test         # run all tests
pnpm typecheck    # type-check all packages
pnpm lint         # prettier check
pnpm smoke        # verify the built server exposes only read-only tools

许可证

MIT。请参阅 LICENSE。

免责声明

这是一个独立的社区项目。它与 Helcim Inc. 无关联，未受其赞助、维护或认可。“Helcim” 是 Helcim Inc. 的商标，此处仅用于描述 API 兼容性。本项目不使用 Helcim 的标志或品牌。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • HighLevel MCP Server

    isaganiesteron
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to manage multiple HighLevel CRM sub-accounts through a single OAuth-based MCP server, providing read-only access to contacts, conversations, opportunities, calendars, payments, blogs, emails, and social media.
    -

  • easypaydirect-mcp

    praveendias1180
    A
    license
    A
    quality
    A
    maintenance
    Read-only MCP server for Easy Pay Direct / NMI payment gateway, enabling natural language queries of transactions, subscriptions, and customer vault records.
    7
    43 npm
    MIT

  • qualys-pci-mcp

    RobotDisco
    A
    license
    A
    quality
    B
    maintenance
    A read-only MCP server for the Qualys PCI Merchant API that lets LLM assistants answer questions about PCI compliance posture, such as which hosts are failing PCI or listing high findings.
    7
    Apache 2.0