Skip to main content
Glama
deenesjakoruzh
tejasghalsasi

helcim-mcp

by tejasghalsasi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

helcim-mcp

非公式のコミュニティMCPサーバーおよびHelcim API用開発者ツールキットです。 安全・型付き・エージェントフレンドリーで、デフォルトで読み取り専用です。 Helcim Inc.とは提携しておらず、スポンサー、メンテナンス、推奨のいずれも受けていません。

helcim-mcp は、AIエージェント（および人間）がHelcim決済プラットフォームを 安全かつ簡単に操作できるようにする、本番品質のTypeScriptモノレポです。 以下の3つを提供します:

  1. @helcim-mcp/server — 読み取り専用のHelcimツール（顧客、請求書、 カード取引、カードバッチ、定期支払いプラン、サブスクリプション、接続テスト）を 公開するMCPサーバー。

  2. @helcim-mcp/core — 型付きで冪等性に対応したHelcim APIクライアント。 エラーの正規化、レート制限の処理、シークレットの秘匿化を備えています。

  3. @helcim-mcp/webhooks — スタンドアロンのHelcimウェブフック検証ライブラリ （HMAC-SHA256署名検証、タイムスタンプ検証、リプレイ保護、型付きイベント）。

なぜこれを使うのか？

  • AIエージェントにHelcimデータについて質問させたい場合 — 「未払いの 請求書はどれ？」「最近のカード取引を表示して」「この請求書の顧客を探して」 「注意が必要なサブスクリプションはどれ？」 — 金銭的な変更（mutation）の リスクを一切負うことなく。

  • APIの癖（HTTP 200 ≠ 成功、errorsオブジェクトの構造、冪等性、レート制限、 ページネーション）を処理してくれる、クリーンで型付きのHelcimクライアントが 欲しい場合 — 自分で処理する必要はありません。

  • Helcimウェブフックを安全に検証したい場合 — 定数時間の署名比較とリプレイ 保護を備えており、HMACスキームを再発明する必要はありません。

MCPサーバーはデフォルトで読み取り専用です。作成、更新、削除、資金移動を 物理的に行うことはできません — そのようなツールは存在しません。完全な処理 権限を持つトークンでも、このサーバーを通じて金銭的な変更を引き起こすことは できません。

Related MCP server: HighLevel MCP Server

クイックスタート

1. Helcim APIトークンを取得する

Helcimアカウント（または開発者テストアカウント）にログインし、 All Tools → Integrations → API Access Configurations に移動して、 設定を作成します。読み取り専用で使用するには、General: Read、 Settings: Read、Transaction Processing: None に設定します。

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 — トークンが機能することを確認します。

  • list_invoices に status: "DUE" を指定 — 「未払いの請求書はどれ？」

  • list_card_transactions — 「最近のカード取引を表示して。」

  • get_customer — 「この請求書の顧客を探して。」

  • list_subscriptions に hasFailedPayments: true を指定 — 「注意が必要なサブスクリプションはどれ？」

読み取り専用モードの仕組み

  • MCPサーバーは読み取り専用ツールのみを公開します。支払い、返金、売上確定、 取消、出金、決済、削除のツールはありません。

  • コアクライアントはv1では書き込みメソッドを一切公開しません。

  • 将来のバージョンで書き込みが追加される場合、明示的な HELCIM_ENABLE_WRITES=true 環境変数および金銭的な変更（mutation）のための 別の高リスク機能フラグが必要となり、充実したドキュメントとテストが伴います。

  • 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

エージェントは資金を動かせません。そのようなツールは存在しません。

ウェブフック検証

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

ウェブフック用

お使いのHelcimウェブフック検証トークン。

完全なリファレンスについては 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