@portlogics/pms-mcp

PMS 포워더용 MCP 서버. Claude Desktop / Claude Code 에서 Master BL · House BL 생성 · 조회 · 수정, 내륙운송, 회계 · 정산, 회사 · 멤버 · 항만 조회 등을 자연어로 수행한다.

설치

npx @portlogics/pms-mcp@latest

@latest 태그를 붙이면 npx가 매 실행 시 npm registry에서 최신 버전을 확인하고 자동으로 업그레이드해 실행한다. 특정 버전에 고정하고 싶으면 @0.1.0 같이 명시.

환경변수

| 변수 | 필수 | 설명 | |------|------|------| | PMS_MCP_PROFILE | 선택 | 환경 프로필 — local / dev / staging / prod (기본값: prod). local 은 http://localhost:8081 로 요청 | | PMS_MCP_USERNAME | 선택 | PMS 로그인 username | | PMS_MCP_PASSWORD | 선택 | PMS 로그인 password | | PMS_MCP_LOG_LEVEL | 선택 | 로그 레벨 (기본값: info) |

Claude Desktop 설정

{
  "mcpServers": {
    "pms": {
      "command": "npx",
      "args": ["-y", "@portlogics/pms-mcp@latest"],
      "env": {
        "PMS_MCP_USERNAME": "your_username",
        "PMS_MCP_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code 설정

프로젝트 .mcp.json:

{
  "mcpServers": {
    "pms": {
      "command": "npx",
      "args": ["-y", "@portlogics/pms-mcp@latest"],
      "env": {
        "PMS_MCP_USERNAME": "your_username",
        "PMS_MCP_PASSWORD": "your_password"
      }
    }
  }
}

주요 기능

🚢 House BL / Master BL

• 통합 상세 조회 (평탄 응답) — BL 번호 한 번으로 기본정보 · 당사자 · 스케줄 · 컨테이너 · 면장 정보를 한 객체로 반환.
• 검색 — 구조화 필터(화주 · 기간 · 포트 · 운송모드 · 담당자 등)로 목록 조회, 필터 후보는 별도 툴로 제공.
• 생성 — 포트 · 화주 ID 자동 해석 포함.
• 수정 (단일 트랜잭션 PATCH) — Patch-presence 방식으로 필드 단위 부분 업데이트. FCL/LCL/면장은 id 기준 전체 치환(update/insert/soft-delete). containerCode 는 enum 제약.
• MBL ↔ HBL 상호 조회 — MBL 에 묶인 HBL 목록, HBL 의 원본 MBL.
• 진행 상태 / 트래킹 / 문서 / 계약 · 통관 — 세부 영역 툴로 보완 조회.

🚛 내륙운송 (Trucking)

• 오더 검색 · 목록 · 상세 — HBL/MBL 기준으로 연결된 내륙운송 오더 조회.
• 세그먼트 검색 / 상세 — 픽업 · 간선 · 배차 단위 세그먼트.
• 위치 · 파일 조회 — 상하차지 검색, 오더 첨부 파일 목록.

💰 회계 · 정산 · 세무

• 거래 검색 및 상세 — 구조화 필터 · 정렬, 필터 옵션 조회.
• 정산 (Settlement) — 캐시플로우 · 단가 · 원가 템플릿 조회, HBL/MBL 원가 저장, 원가 정산서 · 인보이스 생성.
• 재무 통계 — 실적 집계, 필터 옵션 조회.
• 세금계산서 — 발행 가능 여부, 상태, 임시 저장본, 매입 세금계산서 조회, 사업자번호 조회.
• 은행 — 거래 내역, 계좌 목록.

🏢 회사 · 멤버

• 회사 검색 · 상세 · 자사 조회 — 이메일, 사업자번호 포함.
• 회사 멤버 검색 · 목록 — 담당자 ID 를 각종 PATCH/POST 입력으로 연계.

🌐 참조 데이터

• 항만 검색 — 코드 · 이름 · 공항/항구 구분.
• 선사 크롤링 · 자동부킹 · 스케줄 이력, 항공편 목록.
• 공용 검색 필터 (BL/회계/재무).

🔐 인증

• pms_login — 환경변수 설정 시 부팅 타임에 자동 로그인.

사용 예시

• "BL번호 HBL-2501-001 상세 보여줘" → get_house_bl_by_number
• "KRPUS → USLAX 해상 수출 MBL 최근 3개월 검색" → search_master_bl
• "MBL 100 에 연결된 HBL 목록" → get_master_bl_house_bls
• "HBL 7 에 40ft HQ 컨테이너 2개 추가하고 면장 번호 업데이트" → update_house_bl (fcls + exportLicenses 전체 치환)
• "HBL 200 진행 상태 알려줘" → get_hbl_progress
• "이번 달 매출 실적 집계" → search_finance_performance
• "화주 '삼성전자' 찾아줘" → search_company

라이선스

MIT