Invoice RPA MCP Server

Excel 인보이스 파일에서 데이터를 자동 추출하여 표준 출력 템플릿으로 매핑하는 MCP 서버입니다. Claude Desktop, Claude Code, Cursor 등 AI 에이전트에서 인보이스 처리를 호출할 수 있습니다.

Quick Start

요구사항

• Python 3.10+
• uv 패키지 매니저

mcp.json 등록

AI 클라이언트 설정에 아래를 추가하면 자동으로 다운로드+실행됩니다:

{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uvx",
      "args": ["invoice-rpa-mcp"],
      "env": {
        "INVOICE_INPUT_FOLDER": "/path/to/input",
        "INVOICE_OUTPUT_FOLDER": "/path/to/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/path/to/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/path/to/itemList.csv"
      }
    }
  }
}

env의 4개 경로를 실제 환경에 맞게 수정하세요. Windows에서는 슬래시(/)를 사용합니다: "C:/Invoice/input"

설정 파일 위치

클라이언트	파일 위치
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	프로젝트 루트 .mcp.json 또는 claude mcp add CLI
Cursor	프로젝트 루트 .cursor/mcp.json

Claude Code CLI로 추가하는 경우:

claude mcp add invoice-rpa -- uvx invoice-rpa-mcp

Available Tools

인보이스 처리

Tool	설명	파라미터
process_all_invoices	input 폴더의 모든 인보이스 일괄 처리	—
process_single_invoice	특정 파일 1개 처리	filename (str)
list_input_files	처리 대상 파일 목록 및 크기 조회	—
get_server_config	현재 서버 설정 및 로드된 데이터 건수 조회	—

상태 관리

Tool	설명	파라미터
get_history	처리 이력 조회 (어떤 파일이 언제 처리되었는지)	—
reset_history	처리 이력 초기화 (초기화된 파일은 다시 처리 가능)	filename (str, 선택 — 빈값이면 전체 초기화)
get_sequences	인보이스 번호 시퀀스 상태 조회	—
reset_sequence	인보이스 번호 시퀀스 초기화 (1부터 재시작)	key (str, 선택 — 빈값이면 전체 초기화)

Environment Variables

모든 환경변수는 INVOICE_ 접두사를 사용합니다.

환경변수	필수 (uvx)	기본값	설명
INVOICE_INPUT_FOLDER	필수	./input	입력 파일 디렉토리
INVOICE_OUTPUT_FOLDER	필수	./output	출력 파일 디렉토리
INVOICE_CUSTOMER_MASTER_PATH	필수	./variation_data/customer_master.csv	고객 마스터 CSV
INVOICE_ITEM_LIST_PATH	필수	./variation_data/itemList.csv	아이템 리스트 CSV
INVOICE_MCP_TRANSPORT	선택	stdio	Transport: stdio, streamable-http, sse
INVOICE_MCP_HOST	선택	0.0.0.0	HTTP/SSE 바인딩 호스트
INVOICE_MCP_PORT	선택	8000	HTTP/SSE 포트

uvx는 격리 환경에서 실행되므로 기본 경로가 의미 없습니다. 4개 경로는 반드시 설정하세요. 로컬 개발(uv run --directory)에서는 프로젝트 기본 경로가 동작하므로 생략 가능합니다.

Transport 모드별 설정

1. stdio (권장)

AI 클라이언트가 로컬에서 프로세스를 직접 실행합니다.

uvx (권장) — 소스코드 불필요, PyPI에서 자동 다운로드:

{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uvx",
      "args": ["invoice-rpa-mcp"],
      "env": {
        "INVOICE_INPUT_FOLDER": "/path/to/input",
        "INVOICE_OUTPUT_FOLDER": "/path/to/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/path/to/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/path/to/itemList.csv"
      }
    }
  }
}

uv run — 소스코드를 클론한 로컬 개발 환경:

{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/invoice_rpa",
        "invoice-rpa-mcp"
      ]
    }
  }
}

--directory로 프로젝트 루트를 지정하면 기본 경로(./input 등)가 동작하므로 env를 생략할 수 있습니다. 커스텀 경로가 필요하면 env 블록을 추가하세요.

2. Streamable HTTP (원격)

서버에서 HTTP로 호스팅하고 네트워크를 통해 접속합니다. 경로 설정은 서버 측에서 관리합니다.

서버 실행:

INVOICE_MCP_TRANSPORT=streamable-http \
INVOICE_INPUT_FOLDER=/path/to/input \
INVOICE_OUTPUT_FOLDER=/path/to/output \
INVOICE_CUSTOMER_MASTER_PATH=/path/to/customer_master.csv \
INVOICE_ITEM_LIST_PATH=/path/to/itemList.csv \
uvx invoice-rpa-mcp

클라이언트 mcp.json:

{
  "mcpServers": {
    "invoice-rpa": {
      "type": "streamable-http",
      "url": "http://서버IP:8000/mcp"
    }
  }
}

3. SSE (레거시 원격)

Streamable HTTP를 지원하지 않는 클라이언트용입니다. endpoint가 /sse인 것 외에는 동일합니다.

서버 실행:

INVOICE_MCP_TRANSPORT=sse \
INVOICE_INPUT_FOLDER=/path/to/input \
INVOICE_OUTPUT_FOLDER=/path/to/output \
INVOICE_CUSTOMER_MASTER_PATH=/path/to/customer_master.csv \
INVOICE_ITEM_LIST_PATH=/path/to/itemList.csv \
uvx invoice-rpa-mcp

클라이언트 mcp.json:

{
  "mcpServers": {
    "invoice-rpa": {
      "type": "sse",
      "url": "http://서버IP:8000/sse"
    }
  }
}

동작 확인

# MCP Inspector로 테스트 (브라우저에서 tool 목록 확인 및 호출)
npx @modelcontextprotocol/inspector uvx invoice-rpa-mcp

입력 파일 형식

파일명 패턴:

Contract No.DRBVN XXXXX (DD-MM-YYYY) 고객명-위치.xlsx

예시:

Contract No.DRBVN 12345 (15-01-2024) KUBOTA-OSK, JAPAN.xlsx

지원 고객

• 미국: Caterpillar, Bobcat MHE/MT/CTL, GPM, YCENA, JohnDeere
• 일본: Kubota, Yanmar, Takeuchi, CJL, Hitachi, Komatsu
• 인도: Caterpillar India, JCB India, Bobcat India
• 유럽: VolvoFrance, Bobcat CZ, YanmarFrance

개발

# 클론 및 설치
git clone https://github.com/your-repo/invoice_rpa.git
cd invoice_rpa
uv sync

# 로컬 실행
uv run invoice-rpa-mcp

# Standalone 배치 처리
uv run python invoice_rpa_mcp/main.py

# MCP Inspector 테스트
npx @modelcontextprotocol/inspector uv run invoice-rpa-mcp

프로젝트 구조

invoice_rpa/
├── invoice_rpa_mcp/            # Python 패키지
│   ├── mcp_server.py           # MCP 서버 진입점
│   ├── main.py                 # Standalone 배치 진입점
│   ├── invoice_processor.py    # 처리 오케스트레이션
│   ├── data_extractor.py       # 데이터 추출
│   ├── mapper.py               # 데이터 매핑
│   ├── customer_identifier.py  # 고객 식별
│   ├── template_selector.py    # 템플릿 선택
│   ├── sequence_manager.py     # 인보이스 번호 시퀀싱
│   └── utils/                  # 유틸리티
├── config/                     # JSON 설정 파일 (패키지에 포함)
├── templates/                  # Excel 출력 템플릿 (패키지에 포함)
├── variation_data/             # 사용자 CSV 데이터
│   ├── customer_master.csv     # 고객 마스터
│   └── itemList.csv            # 제품 카탈로그
├── input/                      # 입력 파일 디렉토리
└── output/                     # 출력 파일 디렉토리

신규 고객 추가

1. config/customer_patterns.json에 별칭 추가
2. config/customer_types.json의 해당 지역에 추가
3. variation_data/customer_master.csv에 행 추가
4. variation_data/itemList.csv에 제품 항목 추가

License

MIT