@portlogics/pms-mcp

PMS 포워더용 MCP 서버. Claude Desktop / Claude Code 에서 Master BL · House BL 생성 · 조회 · 수정, 채팅 통합검색 · 조회, 내륙운송, 회계 · 정산, 통관(유니패스) · EDI 신고, 회사 · 멤버 · 항만 조회 등을 자연어로 수행한다.

설치

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_ACCESS_TOKEN | 선택 | PMS access token. 설정 시 그대로 헤더에 담아 통신(로그인 생략) | | PMS_MCP_REFRESH_TOKEN | 선택 | PMS refresh token. access token 없이 이것만 있으면 부팅 시 access token 을 발급받아 사용. access token 과 함께 두면 만료 시 자동 재발급에 사용 | | PMS_MCP_USERNAME | 선택 | PMS 로그인 username | | PMS_MCP_PASSWORD | 선택 | PMS 로그인 password | | PMS_MCP_LOG_LEVEL | 선택 | 로그 레벨 (기본값: info) | | PMS_MCP_READONLY | 선택 | true 면 mutating(생성·수정·정산·인보이스·로그인) tool 을 전부 미노출. 일반 챗봇 사용자 대상 조회 전용 배포에 권장 (기본값: false) | | PMS_MCP_DISABLED_TOOLS | 선택 | 노출에서 제외할 tool 이름의 콤마 구분 목록 (운영자 denylist). 예: edi_master_bl,generate_cost_invoice |

조회 전용 배포 시 주의 — PMS_MCP_READONLY=true 는 pms_login 도 숨긴다. 인증 경로가 막히지 않도록 반드시 PMS_MCP_USERNAME / PMS_MCP_PASSWORD 를 함께 설정해 부팅 타임 자동 로그인을 활성화할 것.

인증 우선순위: PMS_MCP_ACCESS_TOKEN > PMS_MCP_REFRESH_TOKEN > PMS_MCP_USERNAME/PMS_MCP_PASSWORD. 위 중 아무것도 없으면 부팅 시 세션을 열지 않고, pms_login 툴로 수동 로그인할 수 있다.

Claude Desktop 설정

토큰 방식 (권장):

{
  "mcpServers": {
    "pms": {
      "command": "npx",
      "args": ["-y", "@portlogics/pms-mcp@latest"],
      "env": {
        "PMS_MCP_ACCESS_TOKEN": "your_access_token",
        "PMS_MCP_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

또는 username / password 방식 (부팅 타임 자동 로그인):

{
  "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_ACCESS_TOKEN": "your_access_token",
        "PMS_MCP_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

또는 username / password 방식:

{
  "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.
• 진행 상태 / 트래킹 / 문서 / 계약 · 통관 — 세부 영역 툴로 보완 조회.

💬 채팅 (Chat)

• 통합검색 (search_chat_messages) — HBL 을 몰라도 키워드/내용으로 포워더의 모든 House BL 채팅 채널 본문을 한 번에 검색. 매칭을 채널 단위로 묶어 채널별 연결 HBL 전부 + 화주 + 담당자 + 매칭 메시지(채널당 최대 200건)를 반환, keyset 페이징.
• 단일 HBL 메시지 조회 (get_house_bl_chat_messages) — 이미 아는 HBL(hblId / blNumber)의 전체 Sendbird 메시지 로그를 최신순 keyset 페이징으로 조회.

🚛 내륙운송 (Trucking)

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

🛃 통관 · EDI

• 유니패스 통관 조회 (get_mbl_unipass) — MBL 기준 통관 BL · 수입신고 · 수출신고 데이터를 한 번에 통합 조회.
• EDI 신고 / 수정 (edi_master_bl) — 해상 수출입 적하목록 · AMS · AFR, 항공 FWB · FHL 의 신고(declare) / 내용 수정(update_info) / MRN·MSN 갱신 / 이력 추가. 해상은 /v3/masterBL, 항공은 /v3/mawb 로 자동 분기.
• EDI 메타 · 내용 조회 (get_mbl_edi_tabs, get_mbl_edi_info) — 해당 MBL 에서 사용 가능한 EDI 유형 탭, 특정 유형의 메시지 상세.

💰 회계 · 정산 · 세무

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

🏢 회사 · 멤버

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

🌐 참조 데이터

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

🔐 인증

부팅 시 우선순위 ACCESS_TOKEN > REFRESH_TOKEN > USERNAME/PASSWORD 로 세션을 초기화한다.

• Access token — PMS_MCP_ACCESS_TOKEN 이 있으면 로그인 없이 그대로 헤더에 담아 통신.
• Refresh token — access token 없이 PMS_MCP_REFRESH_TOKEN 만 있으면 부팅 시 POST /auth/token/refresh 로 access token 을 발급받아 사용.
• 자동 갱신 — 요청이 401 을 받으면 refresh token 으로 access token 을 재발급해 1회 자동 재시도.
• username / password — PMS_MCP_USERNAME/PMS_MCP_PASSWORD 로 부팅 타임 자동 로그인.
• 토큰 · 세션은 메모리에만 저장(휘발성 — 서버 재기동 시 초기화).
• pms_login — 위 환경변수가 없을 때 수동 로그인. 자격증명이 설정돼 있거나 PMS_MCP_READONLY=true 면 tool 목록에서 자동으로 숨겨진다(챗봇 사용자에게 크레덴셜 입력 유도 방지).

사용 예시

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

라이선스

MIT