invoice-rpa-mcp 0.1.0

MCP server for invoice automation — extracts, maps, and outputs standardized invoices from Excel files

인보이스 자동화 RPA 시스템

Excel 파일에서 데이터를 자동으로 추출하여 표준화된 출력 템플릿으로 매핑하는 지능형 인보이스 처리 시스템입니다. 다양한 고객 유형과 레이아웃을 지원합니다.

🚀 주요 기능

핵심 기능

• 동적 셀 참조 매핑: 하드코딩된 셀 위치 없이 설정으로 관리
• 유연한 시트 감지: 별칭과 대체 전략을 통한 지능형 시트 이름 매칭
• 고객 유형 지원: 미국, 일본, 인도, 유럽 고객을 위한 다양한 템플릿
• 자동 번호 생성: 고객별 패턴에 따른 스마트 인보이스 번호 시퀀싱
• 중복 방지: 내장된 중복 확인 및 처리 추적

고급 기능

• 테이블 구조 분석: 자동 헤더 감지 및 컬럼 매핑
• 행 조정: 데이터 양에 따른 동적 행 삽입/삭제
• 수식 적용: 자동 SUM 및 계산 수식
• 통화 처리: 통화 코드가 포함된 자동 헤더 업데이트
• 오류 복구: 상세 로깅을 통한 강력한 오류 처리

📁 프로젝트 구조

invoice_rpa/
├── config/                     # 설정 파일
│   ├── cell_references.json    # 동적 셀 참조 매핑
│   ├── search_config.json      # 검색 범위 및 파라미터
│   ├── sheet_config.json      # 시트 이름 매핑 및 별칭
│   ├── customer_patterns.json  # 고객 식별 패턴
│   ├── customer_types.json     # 고객 유형 분류
│   └── mapping_config.json     # 필드 매핑 규칙
├── invoice_rpa_mcp/            # 소스 코드 (패키지)
│   ├── utils/                  # 유틸리티 클래스
│   │   ├── excel_operations.py # 통합 Excel 작업
│   │   ├── header_detector.py  # 헤더 감지 유틸리티
│   │   ├── table_mapper.py     # 테이블 매핑 작업
│   │   ├── excel_helper.py     # Excel 헬퍼 함수
│   │   └── logger.py           # 로깅 유틸리티
│   ├── config_loader.py        # 설정 관리
│   ├── data_loader.py          # CSV 데이터 로딩
│   ├── data_extractor.py       # Excel에서 데이터 추출
│   ├── mapper.py              # 템플릿으로 데이터 매핑
│   ├── invoice_processor.py   # 메인 처리 오케스트레이션
│   ├── customer_identifier.py  # 고객 식별
│   ├── template_selector.py    # 템플릿 선택 로직
│   ├── duplicate_checker.py    # 중복 감지
│   ├── sequence_manager.py    # 인보이스 시퀀싱
│   ├── filename_normalizer.py # 파일명 정규화
│   └── detail_pl_handler.py   # 상세 P/L 처리
├── variation_data/            # 변수 데이터
│   ├── customer_master.csv    # 고객 마스터 데이터
│   ├── itemList.csv           # 제품 카탈로그
│   └── process_config.json    # 처리 설정
├── templates/                  # Excel 템플릿
│   ├── OUTPUT_BLANKFILE_V2.xlsx  # 표준 템플릿
│   └── OUTPUT_BLANKFILE_US_V2.2.xlsx # 미국 전용 템플릿
├── input/                     # 입력 파일 디렉토리
├── output/                    # 출력 파일 디렉토리
└── logs/                      # 로그 파일 디렉토리

⚙️ 설정

경로 설정 (variation_data/process_config.json)

Standalone 실행(invoice_rpa_mcp/main.py)에서 사용하는 경로 설정입니다. 미설정 항목은 프로젝트 기본 경로를 사용합니다.

macOS / Linux:

{
  "input_folder": "/Users/drb/invoice/input",
  "output_folder": "/Users/drb/invoice/output",
  "customer_master_path": "/Users/drb/invoice/customer_master.csv",
  "item_list_path": "/Users/drb/invoice/itemList.csv"
}

Windows:

{
  "input_folder": "C:/Users/drb/invoice/input",
  "output_folder": "C:/Users/drb/invoice/output",
  "customer_master_path": "C:/Users/drb/invoice/customer_master.csv",
  "item_list_path": "C:/Users/drb/invoice/itemList.csv"
}

Windows 경로 주의사항: JSON에서 백슬래시(\)는 이스케이프 문자입니다. Windows 경로를 입력할 때 슬래시(/)를 사용하세요. C:\Users\drb → "C:/Users/drb". 백슬래시를 사용하려면 이중으로 입력해야 합니다: "C:\\Users\\drb". 이 규칙은 process_config.json, mcp.json, claude_desktop_config.json 등 모든 JSON 설정 파일에 동일하게 적용됩니다.

고객 유형 설정 (config/customer_types.json)

고객 유형별 템플릿과 행 위치를 정의합니다.

매핑 설정 (config/mapping_config.json)

필드 매핑 규칙을 설정합니다.

🏃‍♂️ 사용법

사전 요구사항

• Python 3.13+
• 필수 패키지 (uv로 설치):

uv sync

실행 방법

두 가지 실행 방식을 지원합니다:

방식	명령어	용도
Standalone	uv run python invoice_rpa_mcp/main.py	일괄 배치 처리
MCP 서버	uv run invoice-rpa-mcp	AI 에이전트 연동

Standalone 실행

1. Excel 파일을 input/ 디렉토리에 넣으세요
2. 스크립트 실행:

uv run python invoice_rpa_mcp/main.py

3. 처리된 파일이 output/ 디렉토리에 나타납니다

MCP 서버 실행

아래 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

🔧 아키텍처

핵심 컴포넌트

1. InvoiceProcessor (invoice_rpa_mcp/invoice_processor.py)

전체 처리 워크플로우를 조율하는 메인 오케스트레이터:

• 고객 식별
• 템플릿 선택
• 데이터 추출
• 매핑 및 출력 생성

2. DataExtractor (invoice_rpa_mcp/data_extractor.py)

동적 설정으로 입력 Excel 파일에서 데이터 추출:

• 인보이스 메타데이터 (번호, 날짜, 당사자)
• 운송 정보
• 자동 테이블 감지가 포함된 라인 아이템

3. Mapper (invoice_rpa_mcp/mapper.py)

추출된 데이터를 출력 템플릿으로 매핑:

• 필드 수준 매핑
• 테이블 구조 적응
• 수식 적용

4. 유틸리티 클래스

ExcelOperations (invoice_rpa_mcp/utils/excel_operations.py)

• 통합 Excel 파일 작업
• 별칭이 있는 시트 찾기
• 대체가 포함된 셀 값 추출
• 수식 적용

HeaderDetector (invoice_rpa_mcp/utils/header_detector.py)

• 동적 헤더 감지
• 컬럼 매핑 추론
• 테이블 구조 분석

TableMapper (invoice_rpa_mcp/utils/table_mapper.py)

• 테이블 행 조정
• 데이터 매핑 작업
• 합계 행 처리

처리 흐름

1. 파일 발견: 입력 디렉토리에서 Excel 파일 스캔
2. 고객 식별: 파일명에서 고객 추출
3. 템플릿 선택: 고객 유형에 따라 적절한 템플릿 선택
4. 데이터 추출: 메타데이터, 운송 정보 및 아이템 추출
5. 데이터 매핑: 추출된 데이터를 템플릿 필드로 매핑
6. 행 조정: 아이템 수에 따라 테이블 행 조정
7. 출력 생성: 정규화된 파일명으로 처리된 파일 저장
8. 중복 트래킹: 파일을 처리된 것으로 표시

🌐 MCP 서버

MCP(Model Context Protocol) 서버를 통해 Claude Desktop, Claude Code, Cursor 등 AI 에이전트에서 인보이스 처리 기능을 호출할 수 있습니다.

Transport 모드

모드	프로토콜	용도	mcp.json 키
stdio (기본)	표준 입출력	로컬에서 AI 클라이언트가 프로세스 직접 실행	command + args
streamable-http	HTTP	원격 서버 호스팅, 네트워크 접속	url (endpoint: /mcp)
sse	Server-Sent Events	streamable-http 미지원 클라이언트용 레거시	url (endpoint: /sse)

환경변수

모든 환경변수는 선택사항이며, 미설정 시 프로젝트 디렉토리 기준 기본값을 사용합니다.

환경변수	기본값	설명
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 포트

env 블록에는 변경이 필요한 항목만 선택적으로 설정하세요. uvx로 실행할 경우 프로젝트 디렉토리가 없으므로 4개 경로 환경변수는 필수입니다.

제공 Tool

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

---

1. stdio 모드 — uv run (로컬 개발)

프로젝트 소스를 클론한 로컬 환경에서 사용합니다. --directory로 프로젝트 루트를 지정하면 기본 경로가 동작하므로 env는 커스텀 경로가 필요한 경우에만 설정합니다.

Claude Desktop (claude_desktop_config.json)

설정 파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS / Linux:

{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/Users/username/workspace/invoice_rpa",
        "invoice-rpa-mcp"
      ],
      "env": {
        "INVOICE_INPUT_FOLDER": "/Users/username/invoice/input",
        "INVOICE_OUTPUT_FOLDER": "/Users/username/invoice/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/Users/username/invoice/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/Users/username/invoice/itemList.csv"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "C:/Projects/invoice_rpa",
        "invoice-rpa-mcp"
      ],
      "env": {
        "INVOICE_INPUT_FOLDER": "C:/Invoice/input",
        "INVOICE_OUTPUT_FOLDER": "C:/Invoice/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "C:/Invoice/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "C:/Invoice/itemList.csv"
      }
    }
  }
}

Claude Code (.mcp.json)

프로젝트 루트에 .mcp.json 파일을 생성하거나 CLI로 추가합니다:

{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/Users/username/workspace/invoice_rpa",
        "invoice-rpa-mcp"
      ],
      "env": {
        "INVOICE_INPUT_FOLDER": "/Users/username/invoice/input",
        "INVOICE_OUTPUT_FOLDER": "/Users/username/invoice/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/Users/username/invoice/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/Users/username/invoice/itemList.csv"
      }
    }
  }
}

claude mcp add invoice-rpa -- uv run --directory /path/to/invoice_rpa invoice-rpa-mcp

--directory: 프로젝트 루트의 절대 경로. 기본 경로(./input, ./output 등)를 사용하면 env 블록 전체를 생략할 수 있습니다. Windows: JSON 경로에 슬래시(/)를 사용하세요.

---

2. stdio 모드 — uvx (PyPI 배포 후)

PyPI에 배포된 패키지를 uvx로 설치 없이 바로 실행합니다. 프로젝트 소스가 불필요하며 config/와 templates/는 패키지에 포함되어 있습니다. 단, 사용자 데이터 경로(input, output, customer_master, itemList)는 프로젝트 디렉토리가 없으므로 4개 경로 환경변수가 필수입니다.

Claude Desktop (claude_desktop_config.json)

macOS / Linux:

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

Windows:

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

Claude Code (.mcp.json)

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

uvx는 uv tool run의 단축 명령으로, 패키지를 격리 환경에서 자동 설치+실행합니다. PyPI 배포 전에는 사용할 수 없습니다. 배포: uv build && uv publish

---

3. Streamable HTTP 모드 (원격)

서버 컴퓨터에서 HTTP로 호스팅하고, 다른 컴퓨터에서 네트워크를 통해 접속합니다. 클라이언트는 URL만 지정하며, 경로 설정은 서버 측에서 관리됩니다.

서버 실행

macOS / Linux:

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 \
uv run --directory /path/to/invoice_rpa invoice-rpa-mcp

Windows (PowerShell):

$env:INVOICE_MCP_TRANSPORT="streamable-http"
$env:INVOICE_INPUT_FOLDER="C:/Invoice/input"
$env:INVOICE_OUTPUT_FOLDER="C:/Invoice/output"
$env:INVOICE_CUSTOMER_MASTER_PATH="C:/Invoice/customer_master.csv"
$env:INVOICE_ITEM_LIST_PATH="C:/Invoice/itemList.csv"
uv run --directory C:/Projects/invoice_rpa invoice-rpa-mcp

서버가 http://0.0.0.0:8000/mcp 에서 대기합니다. 포트/호스트 변경: INVOICE_MCP_PORT=9000, INVOICE_MCP_HOST=192.168.1.100

클라이언트 설정

Claude Desktop (claude_desktop_config.json) / Claude Code (.mcp.json):

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

claude mcp add --transport http invoice-rpa http://서버IP:8000/mcp

서버IP를 실제 IP 주소 또는 호스트명으로 교체하세요.

---

4. SSE 모드 (레거시 원격)

Streamable HTTP를 지원하지 않는 클라이언트를 위한 레거시 transport입니다. endpoint가 /sse인 것 외에는 HTTP 모드와 동일합니다.

서버 실행

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 \
uv run --directory /path/to/invoice_rpa invoice-rpa-mcp

서버가 http://0.0.0.0:8000/sse 에서 대기합니다.

클라이언트 설정

Claude Desktop (claude_desktop_config.json) / Claude Code (.mcp.json):

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

claude mcp add --transport sse invoice-rpa http://서버IP:8000/sse

---

동작 확인

# stdio 실행 확인 (Ctrl+C로 종료)
uv run --directory /path/to/invoice_rpa invoice-rpa-mcp

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

# HTTP 서버 응답 확인
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

백그라운드 실행

INVOICE_MCP_TRANSPORT=streamable-http \
nohup uv run --directory /path/to/invoice_rpa invoice-rpa-mcp &

tail -f /path/to/invoice_rpa/logs/mcp_server.log

---

🐛 문제 해결

일반적인 문제

1. 시트를 찾을 수 없음

   • sheet_config.json에서 적절한 별칭 확인
   • 입력 파일에 예상되는 시트가 있는지 확인

2. 헤더 감지 안됨

   • search_config.json 헤더 키워드 검토
   • 검색 범위 파라미터 확인

3. 고객 식별 안됨

   • 파일명이 예상 패턴을 따르는지 확인
   • customer_patterns.json에서 적절한 별칭 확인

4. 템플릿 선택 실패

   • customer_types.json에 고객이 분류되어 있는지 확인
   • templates/ 디렉토리에 템플릿 파일이 있는지 확인

로깅

시스템은 logs/ 디렉토리에 상세한 로그를 생성합니다:

• invoice_automation.log: 메인 처리 로그
• 오류 상세, 처리 상태, 성능 메트릭 포함

📈 성능

처리 속도

• 소형 파일 (≤ 50개 아이템): ~2-3초
• 중형 파일 (51-200개 아이템): ~5-8초
• 대형 파일 (200+개 아이템): ~10-15초

메모리 사용량

• 기본 메모리: ~50MB
• 파일당: 크기에 따라 +5-20MB
• 피크 메모리: 대형 배치 처리 시 ~200MB

🔧 커스터마이징

새로운 고객 유형 추가

1. config/customer_types.json 업데이트:

{
  "customer_types": {
    "NEW_REGION": ["NewCustomer1", "NewCustomer2"]
  },
  "row_positions": {
    "NEW_REGION": {
      "contract_item_start": 20,
      "output_item_start": 35
    }
  }
}

2. 템플릿 생성 templates/OUTPUT_BLANKFILE_NEW_REGION.xlsx

3. config/customer_patterns.json에 고객 패턴 추가

커스텀 셀 매핑

새 필드 추가 또는 기존 필드 수정을 위해 config/cell_references.json 업데이트:

{
  "input_sheets": {
    "custom_section": {
      "sheet_name": "Custom Sheet",
      "cells": {
        "custom_field": {
          "primary": "B10",
          "fallback": "B9"
        }
      }
    }
  }
}

📋 시스템 요구사항

시스템 요구사항

• OS: Windows, macOS 또는 Linux
• Python: 3.13 이상
• 메모리: 최소 4GB RAM
• 저장공간: 100MB 여유 공간

Python 의존성

openpyxl>=3.1.2
python-dotenv>=1.0.0
pillow>=10.0.0
mcp>=1.0.0

📄 라이선스

이 프로젝트는 기업용이며 기밀입니다. 모든 권리는 보유됩니다.

📞 지원

기술 지원이나 질문이 있는 경우:

• logs/ 디렉토리의 로그 파일 확인
• 설정 파일이 올바르게 포맷되어 있는지 확인
• 입력 파일이 예상 형식을 따르는지 확인

---

버전: 0.2.0 마지막 업데이트: 2026-02-17 상태: 운영 가능