헥토파이낸셜 MCP 서버

헥토파이낸셜의 연동 문서를 쉽고 빠르게 검색·조회할 수 있는 MCP 서버입니다.

MCP란? Model Context Protocol의 줄임말로, "AI를 위한 USB-C 포트"라고 불리며, LLM이 외부 데이터와 도구에 표준화된 방식으로 접근할 수 있게 해주는 프로토콜입니다.

📋 개요

이 MCP 서버는 헥토파이낸셜의 연동 문서를 검색하고, 개발자들이 필요한 정보를 빠르게 찾을 수 있도록 도와줍니다. 전자결제(PG), 내통장결제, 간편현금결제, 화이트라벨, 펌뱅킹, 선불, 현금영수증 서비스 관련 문서를 제공합니다.

서버 시작 시 헥토파이낸셜 공식 개발자 포털에서 최신 문서를 자동으로 가져오므로, 항상 최신 연동 가이드를 기준으로 답변합니다.

🛠️ 제공 도구

도구	설명
`search_docs`	키워드 및 카테고리를 통해 헥토파이낸셜 연동 문서를 검색합니다. 카테고리(PG, 내통장결제, 간편현금결제, 화이트라벨)를 명시하면 검색 정확성이 향상됩니다.
`list_docs`	전체 연동 문서 목록을 조회합니다. 카테고리별(PG, 내통장결제, 간편현금결제, 화이트라벨) 필터링을 제공합니다.
`get_docs`	문서 ID 또는 파일명으로 특정 문서의 전체 내용을 조회합니다.
`search_error_code`	오류코드로 원인과 설명을 즉시 조회합니다.
`get_api_endpoint`	자연어 쿼리로 API URL과 HTTP 메서드를 추출합니다.
`get_api_params`	API 요청·응답 파라미터 테이블을 조회합니다.

🚀 사용 방법

요구사항

Python 3.10+
uv 설치 필수
MCP 클라이언트 (Cursor, Claude Desktop 등)

uv 설치

curl -LsSf https://astral.sh/uv/install.sh | sh

시맨틱 검색 활성화 (선택)

기본 설치는 BM25 키워드 검색만 사용합니다. 아래 옵션을 추가하면 BM25 + 시맨틱 하이브리드 검색이 활성화되어 검색 정확도가 향상됩니다.

pip install "hectofinancial-mcp-server[semantic]"

또는 uvx 실행 시:

{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server[semantic]@latest"]
    }
  }
}

🖇️ MCP 클라이언트 연동

Cursor

🔗 원클릭 설정: Cursor에서 바로 설정하기

또는 프로젝트 루트에 .cursor/mcp.json 파일을 생성:

{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server@latest"]
    }
  }
}

VS Code

🔗 원클릭 설정: VS Code에서 바로 설정하기

수동 설정 방법:

VS Code에서 Ctrl+Shift+P (또는 Cmd+Shift+P)를 눌러 명령 팔레트 열기
"Preferences: Open User Settings (JSON)" 검색 후 선택
settings.json 파일에 다음 설정 추가:

{
  "mcp": {
    "servers": {
      "hectofinancial-mcp-server": {
        "command": "uvx",
        "args": [
          "hectofinancial-mcp-server@latest"
        ]
      }
    }
  }
}

Claude Desktop

~/.claude_desktop_config.json 파일에 추가:

{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server@latest"]
    }
  }
}

기타 MCP 클라이언트

다른 MCP 클라이언트에서도 다음과 같은 설정을 사용할 수 있습니다:

{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server@latest"]
    }
  }
}

💬 사용 예시

MCP 클라이언트(Cursor, Claude Desktop 등)에서 다음과 같은 질문들을 시도해보세요:

🔍 연동 가이드 검색

"헥토파이낸셜 신용카드 결제 연동 방법 알려줘"
"내통장결제 API 호출 어떻게 해?"
"간편현금결제 휴대폰 인증 구현법 찾아줘"
"화이트라벨 서비스 사용법 알려줘"

🔧 실제 구현 질문

"PG에서 결제 승인 후 noti 처리는 어떻게 해?"
"내통장결제에서 테스트 환경 URL과 상용 환경 URL 차이점은?"
"간편현금결제에서 정기결제 등록하는 방법 알려줘"
"PG에서 결제 취소 API 사용법은?"

🔎 오류코드 및 API 조회

"0031 오류 원인이 뭐야?"
"결제승인 API 요청 파라미터 보여줘"
"가상계좌 채번 API 엔드포인트 URL 알려줘"
"What is the API endpoint for virtual account payment?"

📄 License

This project is licensed under the MIT License.

Metadata

Release files for hectofinancial-mcp-server 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hectofinancial-mcp-server 0.5.3
File	Size	Uploaded
hectofinancial_mcp_server-0.5.3.tar.gz	710.5 kB	Sep 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hectofinancial-mcp-server 0.5.3
File	Interpreter	ABI	Platform	Reset
hectofinancial_mcp_server-0.5.3-py3-none-any.whl 1.3 MB Sep 14, 2026	Python 3	none	any	Details

Total release size: 2.0 MB

Release files / hectofinancial_mcp_server-0.5.3.tar.gz

Download URL	hectofinancial_mcp_server-0.5.3.tar.gz
Size	710.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`d1ef57743de5f593ac45056af9cc2db20c3efe1b013c3aafa618210df956413e`
BLAKE2b-256 checksum How to use checksums	`73b943ccf1a21306a61567c42bc90d3df5028af81977ff1e2ef0206cab7e8e4f`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Hecto-Financial/hectofinancial-mcp-server
Publishing commit: github.com/Hecto-Financial/hectofinancial-mcp-server/tree/b2c4a9a0846133f3a5c92884a3577bfa9673b16e

Workflow

Publishing configuration: github.com/Hecto-Financial/hectofinancial-mcp-server/blob/b2c4a9a0846133f3a5c92884a3577bfa9673b16e/.github/workflows/publish.yml
Publishing logs: github.com/Hecto-Financial/hectofinancial-mcp-server/actions/runs/34910076963/attempts/1

Artifact

Subject: hectofinancial_mcp_server-0.5.3.tar.gz
SHA-256 checksum: d1ef57743de5f593ac45056af9cc2db20c3efe1b013c3aafa618210df956413e Verifying attestations

Release files / hectofinancial_mcp_server-0.5.3-py3-none-any.whl

Download URL	hectofinancial_mcp_server-0.5.3-py3-none-any.whl
Size	1.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`ce9b09213f60de3171f4730fe8f5809debfa1496400668e32a0bce7b133d6693`
BLAKE2b-256 checksum How to use checksums	`b3932301c41eedaf591d6c67ac60231b9097cc18bb174884facadc38b032d359`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Hecto-Financial/hectofinancial-mcp-server
Publishing commit: github.com/Hecto-Financial/hectofinancial-mcp-server/tree/b2c4a9a0846133f3a5c92884a3577bfa9673b16e

Workflow

Publishing configuration: github.com/Hecto-Financial/hectofinancial-mcp-server/blob/b2c4a9a0846133f3a5c92884a3577bfa9673b16e/.github/workflows/publish.yml
Publishing logs: github.com/Hecto-Financial/hectofinancial-mcp-server/actions/runs/34910076963/attempts/1

Artifact

Subject: hectofinancial_mcp_server-0.5.3-py3-none-any.whl
SHA-256 checksum: ce9b09213f60de3171f4730fe8f5809debfa1496400668e32a0bce7b133d6693 Verifying attestations