fin-products-tools

Fin Products Tools (금융상품 조회 MCP·CLI 도구)

금융감독원 금융상품한눈에 Open API를 기반으로 금융상품을 조회하는 MCP·CLI 도구입니다. 예적금, 연금저축, 주택담보대출, 전세자금대출, 개인신용대출 데이터를 일관된 MCP 및 CLI 인터페이스로 조회할 수 있습니다.

Fin Products Tools is an MCP/CLI tool for querying financial product datasets based on FSS Open APIs. It provides a consistent MCP and CLI interface for these financial product datasets.

Architecture

• Client: src/fss_tools/clients/fss_client.py
• Service/normalization: src/fss_tools/services/data_service.py
• CLI: src/fss_tools/cli/main.py
• MCP: src/fss_tools/mcp/server.py

Implemented API coverage

• 금융상품한눈에 (finlife)
• saving (적금)
• deposit (정기예금)
• pension_saving (연금저축)
• mortgage (주택담보대출)
• jeonse (전세자금대출)
• personal_loan (개인신용대출)

Setup

cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

Set env vars:

export FSS_API_KEY="your_api_key"
export OUTPUT_FORMAT="json"  # or "table"

Commands

# 기본
fin-products --help

# 금융상품
# 회사 먼저 검색해서 코드 확인
fin-products search-financial-company "농협"

# 회사코드로 정기예금 검색 (회사 코드 생략 시 전체 검색)
# query는 finlife 명세상 financeCd(회사코드/회사명)로 매핑됨
fin-products products --kind deposit --query "농협"
fin-products products --kind deposit --company-code 0013175 --query "농협"

MCP server setup

1) Install package

python -m venv .venv
source .venv/bin/activate
pip install -e .

2) Set environment variables

export FSS_API_KEY="your_api_key"
export OUTPUT_FORMAT="json"

3) Run MCP server (stdio)

fin-products-mcp

4) Example MCP client config (Claude Desktop)

claude_desktop_config.json example:

{
  "mcpServers": {
    "fin-products-tools": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "cd /path/to/fin-products-tools && source .venv/bin/activate && export FSS_API_KEY=YOUR_API_KEY && fin-products-mcp"
      ]
    }
  }
}

MCP tools

1) search_financial_company(query, page=1, size=20, top_group="020000")

• 금융회사 검색 (회사코드 조회용)
• 권장 사용: 먼저 회사 검색 → company_code 확보 → 상품 툴 정밀 조회

2) search_savings(query=None, company_code=None, page=1, size=20, top_group="020000", all_groups=False)

• 적금 상품 조회 (savingProductsSearch)
• query는 내부적으로 financeCd로 매핑됨
• company_code 지정 시 query보다 우선
• all_groups=True면 은행(020000)+저축은행(030300) 통합 조회

3) search_deposits(query=None, company_code=None, page=1, size=20, top_group="020000", all_groups=False)

• 정기예금 상품 조회 (depositProductsSearch)
• query/company_code 우선순위는 위와 동일
• all_groups=True면 은행(020000)+저축은행(030300) 통합 조회

4) search_pension_saving(query=None, company_code=None, page=1, size=20, top_group="020000", all_groups=False)

• 연금저축 상품 조회 (annuitySavingProductsSearch)
• 기본: all_groups=False → top_group 단일 조회
• 통합: all_groups=True → 보험(050000)+금융투자(060000) 병합 조회 (중복 제거)

5) search_mortgage(query=None, company_code=None, page=1, size=20, top_group="020000")

• 주택담보대출 상품 조회 (mortgageLoanProductsSearch)

6) search_jeonse(query=None, company_code=None, page=1, size=20, top_group="020000")

• 전세자금대출 상품 조회 (rentHouseLoanProductsSearch)

7) search_personal_loan(query=None, company_code=None, page=1, size=20, top_group="020000")

• 개인신용대출 상품 조회 (creditLoanProductsSearch)

top_group(권역코드) 참고

• 020000: 은행
• 030200: 여신전문
• 030300: 저축은행
• 050000: 보험
• 060000: 금융투자

Tests

PYTHONPATH=src python3 -m pytest -q