Skip to main content
Glama
deenesjakoruzh
tejasghalsasi

helcim-mcp

by tejasghalsasi
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

helcim-mcp

비공식(unofficial) 커뮤니티 MCP 서버이자 Helcim API 개발 도구 키트입니다. 안전하고, 타입이 지정되어 있으며, 에이전트 친화적이고, 기본적으로 읽기 전용입니다. Helcim Inc.와 제휴·후원·유지·보증 관계가 전혀 없는 프로젝트입니다.

helcim-mcp는 안전하고 손쉽게 AI 에이전트(그리고 사람)가 Helcim 결제 플랫폼을 사용할 수 있도록 만든, 프로덕션 품질 기반의 TypeScript 모노레포입니다. 제공되는 것은 세 가지입니다.

  1. @helcim-mcp/server — Helcim 읽기 전용 도구(고객, 인보이스, 카드 거래, 카드 배치, 정기 결제 플랜, 구독, 연결 테스트)를 노출하는 MCP 서버.

  2. @helcim-mcp/core — 정규화된 오류, 요청 속도 제한(idle rate-limit) 처리, 비밀 값 마스킹(redaction)을 갖춘 타입 안전·멱등성을 고려한 Helcim API 클라이언트.

  3. @helcim-mcp/webhooks — 독립형 Helcim 웹훅 검증기(HMAC-SHA256 서명 검증, 타임스탬프 검증, replay 방지, 타입 이벤트).

이것을 왜 사용해야 하나요?

  • Helmim 데이터에 대해 AI 에이전트에게 질문을 — "어떤 인보이스가 남아있나?", "최근 카드 거래를 보여줘", "이 인보이스에 해당하는 고객을 찾아줘", "주의가 필요한 구독은?" — 금전적인 변화를 감수하지 않고 답을 얻고 싶다면.

  • 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 등)에 아래를 추가하세요:

{
  "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 서버는 조회(read) 도구만 노출합니다. 결제·환불·캡처·취소·출금·정산·삭제 도구는 존재하지 않습니다.

  • 핵심 클라이언트는 v1에서 쓰기 메서드를 노출하지 않습니다.

  • 추후 버전에서 쓰기 기능을 추가하게 된다면, 명시적인 HELCIM_ENABLE_WRITES=true 환경 변수 와 금융 변화를 허용하는 별도의 고위험 기능 플래그, 그리고 충분한 제제, 문서/테스트가 뒷받침되어야 합니다.

  • HTTP 200은 성공으로 취급하지 않습니다. Helcim은 200 응답이 요청한 동작의 성공을 의미하지는 않음을 분명히 정고하며, 클라이언트는 응답 본문의 errors를 타입 오류로 처리하여 밝힙니다.

자격 증명 보호 방식

  • API 토큰은 HELCIM_API_TOKEN 환경 변수에서만 읽습니다. 하드코딩·커밋·로그에 절대 기록하지 않습니다.

  • 모든 로그 대상 및 오류 메시지는 redact()를 거칩니다. 토큰 형태 문자열, 카드 번호, F6L4 값은 <redacted-...>로 치환됩니다.

  • 토큰이 모델(LLM)에 노출되는 일은 없습니다. 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 }
  ] }

에이전트: "최근 card 거래를 보여주세요."

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.와 제휴, 후원, 유지, 보증을 받지 않습니다. "Helmim"은 Helcim Inc.의 상표이며, 여기서는 API 호환성을 설명하기 위해서만 사용됩니다. 본 프로젝트는 Please use Helcim 로고나 브랜딩을 사용하지 않습니다.

This server cannot be installed

-
license - not tested
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)

Resources

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

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