finary-mcp

Finary를 위한 의도적으로 읽기 전용으로 설계된 Model Context Protocol 서버로, 비공식 finary-uapi 클라이언트를 기반으로 합니다.

[!WARNING] 이 프로젝트는 Finary와 독립적이며 Finary의 보증, 지원 또는 유지 관리를 받지 않습니다. finary-uapi를 통해 비공개적이고 문서화되지 않은 엔드포인트에 의존합니다. 두 프로젝트 중 어느 하나라도 예고 없이 동작이 중단될 수 있습니다. 금융, 세금, 법률 또는 투자 조언이 아닙니다.

안전 모델

finary-mcp는 의도적으로 범위를 좁힌 읽기 전용 어댑터입니다:

• 프로필, 조직, 기관, 포트폴리오 및 거래 조회만 노출합니다.

• 로그인, 계정 가져오기, 생성, 업데이트, 삭제, 이체, 거래 또는 일반 CLI 도구가 없습니다.

• 고정된 허용 목록(allowlist)에서 셸 없이 finary-uapi 명령을 구성합니다.

• 필터 값은 실행 전에 검증됩니다.

• 요청이 실패하면 업스트림 stdout/stderr를 반환하지 않습니다. 업스트림 로그인 흐름이 세션 자료를 출력할 수 있기 때문입니다.

• 상태 디렉터리는 명시적입니다(FINARY_MCP_STATE_DIR). 임의의 작업 디렉터리에서 토큰을 찾지 않습니다.

이를 통해 MCP를 통한 의도치 않은 쓰기를 줄입니다. 그러나 다른 프로세스가 세션 파일을 읽을 수 있다면 머신을 안전하게 만들지 못합니다. 신뢰하는 계정과 프로필에서만 서버를 실행하세요.

중요한 인증 주의사항

“읽기 전용”은 Finary 포트폴리오 데이터를 의미합니다. finary-uapi는 요청 전에 Clerk 세션을 갱신하고 jwt.json을 재작성할 수 있습니다. 따라서 MCP 도구가 Finary 데이터를 변경하지 않더라도 개인 상태 디렉터리는 로컬 서비스 계정이 계속해서 쓸 수 있어야 합니다. 서버는 해당 파일, 쿠키 또는 하위 프로세스 진단 정보를 절대 반환하지 않습니다.

finary-uapi는 또한 fuzzywuzzy를 전이적 GPL-2.0 의존성으로 가져옵니다. 의도한 배포 또는 운영 방식에 대해 업스트림 의존성 그래프와 라이선스 영향을 검토하세요.

Related MCP server: C6 Bank MCP

사전 요구 사항

• Python 3.10 이상.

• finary-uapi로 이미 생성된 로컬 Finary 세션.

• jwt.json과 localCookiesMozilla.txt를 모두 포함하는 개인 디렉터리. 디렉터리는 0700 모드, 파일은 0600 모드여야 합니다.

서버는 Google OAuth를 자체적으로 지원하지 않습니다. 로컬 세션을 생성하거나 갱신하려면 finary-uapi가 지원하는 인증 프로세스를 따르세요. 비밀번호, TOTP 코드, JWT, 쿠키 내보내기 파일 또는 세션 파일을 에이전트, 저장소, 이슈 트래커 또는 채팅에 절대 보내지 마세요.

설치

python -m venv .venv
. .venv/bin/activate
pip install finary-mcp

체크아웃에서 개발하는 경우:

pip install -e '.[dev]'
pytest -q

MCP 호스트 구성

FINARY_MCP_STATE_DIR을 Finary 세션이 저장된 디렉터리로 설정하세요. finary-uapi가 별도의 가상 환경에 설치된 경우 FINARY_UAPI_PYTHON을 해당 환경의 Python 실행 파일로 설정하세요.

일반적인 stdio 구성 예시:

{
  "mcpServers": {
    "finary": {
      "command": "/path/to/finary-mcp/.venv/bin/finary-mcp",
      "env": {
        "FINARY_MCP_STATE_DIR": "/private/path/to/finary-state",
        "FINARY_UAPI_PYTHON": "/path/to/finary-uapi/.venv/bin/python"
      }
    }
  }
}

절대 경로를 사용하세요. 상태 디렉터리는 개인 데이터이므로 절대 커밋해서는 안 됩니다. 제공된 .gitignore는 알려진 세션 파일을 제외합니다.

Hermes Agent 예시

mcp_servers:
  finary:
    command: /path/to/finary-mcp/.venv/bin/finary-mcp
    env:
      FINARY_MCP_STATE_DIR: /private/path/to/finary-state
      FINARY_UAPI_PYTHON: /path/to/finary-uapi/.venv/bin/python
    tools:
      include:
        - finary_me
        - finary_organizations
        - finary_institution_connections
        - finary_portfolio
        - finary_transactions

자격 증명을 공개 구성 파일에 복사하지 말고 Hermes의 MCP/구성 워크플로를 통해 이 구성을 추가하세요. 서버를 추가한 후 도구 검색이 다시 실행되도록 Hermes 프로세스를 다시 시작하세요.

도구

의존성: finary-uapi

이 프로젝트는 Finary API의 재구현이 아니라 어댑터입니다. lasconic/finary_uapi 프로젝트의 finary-uapi CLI를 호출하며, 해당 패키지는 현재 pyproject.toml에 finary-uapi>=0.2.3,<0.3으로 선언되어 있습니다.

이 의존성은 문서화되지 않은 Finary 엔드포인트를 사용하고 로컬 세션을 유지합니다. 이 서버를 사용하기 전에 해당 소스와 라이선스를 검토하세요. 업스트림 업그레이드가 필요하면 먼저 별도의 환경에서 테스트한 후 여기에 호환되는 버전을 고정하세요.

개발

pytest -q
python -m build

테스트는 실제 Finary 계정을 사용하지 않으며 세션 파일을 생성해서는 안 됩니다. 게시 전에 스테이징된 파일에서 jwt.json, localCookiesMozilla.txt, 자격 증명, 이메일, 쿠키 및 토큰을 검사하세요.

라이선스

MIT. LICENSE를 참조하세요.