아키텍처

개요

┌─────────────────┐    stdio     ┌────────────────────┐     COM      ┌─────────┐
│   MCP 클라이언트  │ ───────────→ │ mcp-server-xlwings │ ───────────→ │  Excel   │
│ (Claude, Cursor  │ ←─────────── │    (Python/MCP)    │ ←─────────── │ 프로세스  │
│  Windsurf 등)    │   JSON-RPC   └────────────────────┘  Win32 API   └─────────┘
└─────────────────┘

계층 구조

MCP 클라이언트

Claude Desktop, Claude Code, Cursor, Windsurf, Roo Code, Continue 등 Model Context Protocol을 지원하는 모든 클라이언트입니다. stdio를 통해 JSON-RPC로 도구 호출을 전송합니다.

MCP 서버

FastMCP로 구동되는 Python 프로세스입니다. 도구 호출을 수신하여 xlwings 작업으로 변환하고 구조화된 JSON 응답을 반환합니다. 완전히 무상태로 동작하여 세션 관리가 필요 없습니다.

COM 자동화 (xlwings)

Windows COM을 통해 실행 중인 Excel 프로세스에 연결합니다(Windows 전용). VBA 매크로가 사용하는 것과 동일한 인터페이스로, DRM 보호 및 암호화된 문서를 포함하여 Excel이 열어둔 모든 파일에 접근할 수 있습니다.

Excel 프로세스

실제 Microsoft Excel 애플리케이션입니다. 파일, 수식, 매크로, 서식을 관리합니다. MCP 서버가 작업하는 동안 사용자도 동시에 Excel에서 작업할 수 있습니다.

설계 원칙

무상태

세션 ID나 연결 관리가 없습니다. 각 도구 호출이 독립적으로 활성 Excel 인스턴스를 찾습니다. 호출 사이에 Excel을 재시작해도 다음 호출이 자동으로 재연결됩니다.

활성 워크북 기본값

모든 도구는 workbook을 생략하면 활성 워크북을 기본으로 사용합니다. 가장 일반적인 경우인 사용자가 현재 열어둔 파일 작업 시 파일 경로 지정이 불필요합니다.

요약 우선

read_data()에 cell_range를 지정하지 않으면 전체 데이터 대신 시트 구조(크기, 헤더, 병합 셀, 영역)를 반환합니다. 에이전트가 특정 범위를 읽기 전에 시트 레이아웃을 파악할 수 있어 컨텍스트 윈도우를 절약합니다.

최소 도구 수

11개 도구로 Excel 작업 전체를 지원합니다. 관련 동작은 통합되어 있어 (예: manage_workbooks가 list/open/save/close/recalculate 처리) LLM 컨텍스트 오버헤드를 줄입니다.