de en es ja ko ru zh

helcim-mcp

Name: helcim-mcp
Author: tejasghalsasi

by tejasghalsasi

Overview Schema Related Servers Score Discussions

TypeScript

Remote

helcim-mcp

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

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

@helcim-mcp/server — 読み取り専用のHelcimツール（顧客、請求書、カード取引、カードバッチ、定期支払いプラン、サブスクリプション、接続テスト）を公開するMCPサーバー。
@helcim-mcp/core — 型付きで冪等性に対応したHelcim APIクライアント。エラーの正規化、レート制限の処理、シークレットの秘匿化を備えています。
@helcim-mcp/webhooks — スタンドアロンのHelcimウェブフック検証ライブラリ（HMAC-SHA256署名検証、タイムスタンプ検証、リプレイ保護、型付きイベント）。

なぜこれを使うのか？

AIエージェントにHelcimデータについて質問させたい場合 — 「未払いの請求書はどれ？」「最近のカード取引を表示して」「この請求書の顧客を探して」「注意が必要なサブスクリプションはどれ？」 — 金銭的な変更（mutation）のリスクを一切負うことなく。
APIの癖（HTTP 200 ≠ 成功、errorsオブジェクトの構造、冪等性、レート制限、ページネーション）を処理してくれる、クリーンで型付きのHelcimクライアントが欲しい場合 — 自分で処理する必要はありません。
Helcimウェブフックを安全に検証したい場合 — 定数時間の署名比較とリプレイ保護を備えており、HMACスキームを再発明する必要はありません。

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

クイックスタート

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 installed

license - not tested

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

classquill-mcp
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
saagarpatel.dev Portfolio
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
BankBridge
Read-only bank access for your AI agent. Connects Claude, ChatGPT, Cursor, Gemini, Codex.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tejasghalsasi/helcim-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server