excel-mcp-server

Excel MCP Server
Claude, Cursor, VS Code Copilot, Codex 및 기타 AI 클라이언트가 Excel 파일을 생성, 읽기, 편집할 수 있게 해주는 오픈소스 Model Context Protocol(MCP) 서버입니다:
차트, PivotTable, 수식, 표 등. openpyxl 을 기반으로 하며, Microsoft
Excel 이 필요 없고 Windows, macOS, Linux에서 실행됩니다.

excelmcpserver.com 에서 설치하고 사용해 보거나, 아래의
Quick start를 참고하세요.

Features
Charts and PivotTables

AI로 Excel 차트 생성: column, bar, line, area, pie, doughnut, radar, scatter,
bubble, 콤보, 보조 축, 추세선, 오차 막대 지원
Excel 2016 차트 유형: waterfall, histogram, Pareto, box and whisker, treemap, sunburst,
funnel
Excel이 새로 고치는 실제 PivotTable(그룹화, 계산된 필드, "show values as",
레이아웃, 필터)과 PivotTable 및 표용 슬라이서, 타임라인
스파크라인(line, column, win/loss)

Formulas and dynamic arrays

수식은 내장 엔진으로 Excel 없이 계산됩니다(약 260개 함수, 실제 Excel에서 기록한
2,500개 이상의 수식으로 검증). 따라서 Excel에서 한 번도 열지 않은 파일도
read_range가 값을 반환합니다
동적 배열( FILTER , SORT , UNIQUE , SEQUENCE , LET )은 Excel이 저장하는 방식대로
저장되며 옆 셀로 spill됩니다
숫자가 왜 틀렸는지 확인: 시트, 이름, 표를 넘나드는 선행/종속 셀 추적, Excel의
Evaluate Formula처럼 수식을 단계별로 평가
Goal Seek: 수식이 원하는 값에 도달할 때까지 입력값 변경

Data, tables and rules

셀, 날짜, 하이퍼링크 읽기/쓰기, 합계 행과 계산된 열이 있는 표
조건부 서식(색조, 데이터 막대, 아이콘 집합, 상위/하위, 중복, 텍스트, 날짜),
데이터 유효성 검사(드롭다운, 제한, 입력 메시지)
정렬, 필터(조건 포함), 찾기 및 바꾸기, 중복 제거, 텍스트 나누기, 계열 채우기,
선택하여 붙여넣기
글꼴, 채우기, 테두리, 숫자 서식, 병합된 셀, 틀 고정, 그룹화, 인쇄 설정,
시트 보호, 이미지, 메모, 정의된 이름. Excel에서처럼 행과 열을 삽입하거나 삭제하면
모든 참조가 갱신됩니다

Large files

읽기는 워크북을 스트리밍하고 페이지를 반환하므로 수십만 행이 있는 시트에서도
메모리가 일정하게 유지됩니다. 모든 호출은 크기와 셀 제한으로 제한됩니다
1 MB 이상의 XML 시트 편집은 건드리는 행만 파싱하므로, 행과 열 삽입/삭제, 정렬,
바꾸기, 시트 복사, PivotTable 생성이 200,000행 시트에서 몇 분이 아니라 몇 초 만에
완료됩니다

Macros (opt-in)

.xlsm 파일의 VBA 코드 읽기. VBA 쓰기는 서버를
--allow-vba-write 로 시작하지 않는 한 꺼져 있습니다. 서버는 매크로를 실행하지 않습니다

Safe by design

선택적 폴더 제한, 수식 안전 검사, 읽기 전용 모드, 기본적으로 localhost 전용 HTTP,
그리고 반쯤 쓰인 파일을 남기지 않는 원자적 저장

.xlsx , .xlsm (매크로 보존), .xltx , .xltm 파일과 함께 작동합니다. 기존
스레드 댓글, 도형, 양식 컨트롤 및 도구가 편집할 수 없는 기타 콘텐츠는 그대로
유지됩니다.

Quick start
uv 가 필요합니다. 모든 클라이언트는
uvx excel-mcp-server stdio 로 서버를 실행합니다. /path/to/workbooks 를 서버가
사용할 수 있는 폴더로 바꾸세요. excelmcpserver.com 에는 복사
버튼과 Cursor 및 VS Code용 원클릭 설치 링크가 있는 동일한 단계가 있습니다.

Claude Desktop (Chat) : 최신 릴리스에서
excel-mcp-server.mcpb
를 다운로드하여 여세요. Claude가 서버가 사용할 수 있는 폴더를 묻습니다.

Claude Code (CLI 및 Claude Desktop의 Code 탭):

claude mcp add excel --scope user -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks
Cursor ( ~/.cursor/mcp.json ) 및 mcpServers 설정을 사용하는 대부분의 클라이언트:

{
"mcpServers" : {
"excel" : {
"command" : " uvx " ,
"args" : [ " excel-mcp-server " , " stdio " , " --allow-dir " , " /path/to/workbooks " ]
}
}
}
VS Code with GitHub Copilot ( .vscode/mcp.json , servers 키에 주의):

{
"servers" : {
"excel" : {
"type" : " stdio " ,
"command" : " uvx " ,
"args" : [ " excel-mcp-server " , " stdio " , " --allow-dir " , " ${workspaceFolder} " ]
}
}
}

OpenAI Codex, Gemini CLI, Devin Desktop, and Claude Desktop without the bundle
OpenAI Codex (CLI, IDE 확장 및 앱):

codex mcp add excel -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks
Gemini CLI :

gemini mcp add -s user excel uvx excel-mcp-server stdio --allow-dir /path/to/workbooks
Devin Desktop :

devin mcp add -s user excel -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks
Claude Desktop, 수동 설정 : Settings, Developer, Edit Config를 열고 위의 mcpServers
JSON을 claude_desktop_config.json 에 추가한 뒤 Claude를 재시작하세요.

데스크톱 앱은 셸의 PATH를 보지 못하기 때문에 uvx 를 찾지 못하는 경우가 많습니다
(macOS에서 흔함). 대신 which uvx 가 출력하는 전체 경로를 사용하세요.

Choosing which files it can use
--allow-dir DIR 을 사용하면 서버는 DIR 내부(하위 폴더 포함)의 워크북만 열며,
reports/q1.xlsx 같은 상대 경로는 그곳에서 시작합니다. 플래그를 반복하여 여러
폴더를 허용하거나 EXCEL_FILES_PATH 를 설정하세요(macOS/Linux에서는 : , Windows에서는 ; 로
폴더 구분).

--allow-dir 없이는 Excel 파일의 모든 절대 경로가 작동합니다. 모든 모드에서 서버는
Excel 파일만 건드리며 기존 워크북을 조용히 덮어쓰지 않습니다.

Remote use (Streamable HTTP)
uvx excel-mcp-server streamable-http --allow-dir /srv/workbooks
클라이언트는 http://127.0.0.1:8017/mcp 에 연결합니다. 워크북은 --allow-dir 폴더
(기본값 ./excel_files )에 있으며, export_workbook / import_workbook 이
서버와 클라이언트 간에 파일을 이동합니다.

서버는 localhost에서만 수신합니다. 다른 머신을 허용하려면 토큰과 호스트를 설정하세요:

EXCEL_MCP_AUTH_TOKEN=change-me uvx excel-mcp-server streamable-http --host 0.0.0.0
그러면 클라이언트는 Authorization: Bearer change-me 를 보냅니다. 네트워크를 넘어
사용하려면 앞에 TLS 종료 리버스 프록시를 두세요.

Docker
docker build -t excel-mcp-server .
docker run -p 8017:8017 -v " $PWD /workbooks:/data " -e EXCEL_MCP_AUTH_TOKEN=change-me excel-mcp-server
Configuration

Flag
Environment variable
Default
Meaning

--allow-dir DIR
EXCEL_FILES_PATH
none (stdio), ./excel_files (HTTP)
워크북이 있어야 하는 폴더

--read-only
EXCEL_MCP_READ_ONLY=1
off
파일을 변경하지 않는 도구만 제공

--allow-vba-write
EXCEL_MCP_ALLOW_VBA_WRITE=1
off
VBA 매크로를 쓰는 도구 추가(아래 경고 참고), --read-only 와 함께면 무시됨

--tools AREAS
EXCEL_MCP_TOOLS
all
컨텍스트를 절약하기 위해 핵심 도구와 이 쉼표로 구분된 영역만 제공( Choosing tools 참고)

--max-file-mb N
EXCEL_MCP_MAX_FILE_MB
100
서버가 여는 최대 워크북 크기. 열거나 업로드하는 모든 워크북이 지켜야 하는 압축 해제 크기 제한(이 값의 10배)도 설정하며, 500:1을 초과해 압축된 부분은 거부됨

--max-cells N
EXCEL_MCP_MAX_CELLS
100000
한 호출이 읽거나 쓰거나 서식을 지정할 수 있는 최대 셀 수. 읽기는 여전히 페이지로 반환됨

--max-pivot-cells N
EXCEL_MCP_MAX_PIVOT_CELLS
3000000
PivotTable 원본의 최대 셀 수(230,000행, 13열 시트). 가장 큰 원본에서 생성하는 데 약 1분과 약 2 GB 메모리가 소요됨

--max-loaded-cells N
EXCEL_MCP_MAX_LOADED_CELLS
3000000
한 번에 메모리에 로드할 수 있는 워크북의 최대 셀 및 행 수(각 약 0.5 KB, 3,000,000 제한은 약 1.5 GB). 더 큰 워크북은 전체 시트를 로드해야 하는 도구에서 거부됨. read_range 및 기타 스트리밍 읽기, 일부 행만 파싱하는 큰 시트 편집은 시트 크기에 제한받지 않음

--log-level LEVEL

WARNING
stderr에 로깅

--host HOST
EXCEL_MCP_HOST
127.0.0.1
HTTP 수신 주소

--port PORT
EXCEL_MCP_PORT
8017
HTTP 포트

EXCEL_MCP_AUTH_TOKEN
none
HTTP 요청에 필요한 Bearer 토큰

--allow-unauthenticated

off
토큰 없이 비로컬 --host 허용

Tools

Area
Tools

Workbooks
create_workbook , describe_workbook , set_workbook_settings , list_workbooks , export_workbook , import_workbook

CSV
import_csv , export_csv

Sheets
describe_sheet , create_sheet , rename_sheet , copy_sheet , delete_sheet , insert_rows_or_columns , delete_rows_or_columns

Cells
read_range , write_range , clear_range , copy_range , sort_range , transform_range , find_cells , replace_cells

Formulas
trace_formula , goal_seek

Formatting
format_range , merge_cells , set_sheet_layout , add_conditional_format , add_data_validation

Objects
set_table , create_chart , delete_chart , create_pivot_table , delete_pivot_table , add_slicer , delete_slicer , insert_image , delete_image , add_sparklines , delete_sparklines

Names and notes
set_defined_name , delete_defined_name , set_note , delete_note

Macros
read_vba ; --allow-vba-write 사용 시: write_vba_module , delete_vba_module

Choosing tools
모든 도구는 모든 요청에서 컨텍스트를 소비합니다. --tools 는 핵심 도구
( describe_workbook , describe_sheet , read_range )와 나열한 영역만 제공합니다. 예를 들어
uvx excel-mcp-server stdio --tools data,charts 입니다. --read-only (영역의 읽기 전용 도구) 및
--allow-vba-write ( vba 영역도 필요)와 함께 사용할 수 있습니다. 알 수 없는 영역은
서버를 시작 시 중단시키고 유효한 영역을 나열합니다. 크기는 도구 설명과
스키마의 문자 수이며, 토큰당 약 3.5자입니다:

Area
Tools
Characters

core (항상)
describe_workbook , describe_sheet , read_range
8,900

workbooks
create_workbook , set_workbook_settings , list_workbooks , export_workbook , import_workbook
2,600

csv
import_csv , export_csv
2,200

sheets
create_sheet , rename_sheet , copy_sheet , delete_sheet , insert_rows_or_columns , delete_rows_or_columns
2,000

data
write_range , clear_range , copy_range , sort_range , transform_range , find_cells , replace_cells
6,700

formulas
trace_formula , goal_seek
1,300

formatting
format_range , merge_cells , set_sheet_layout , add_conditional_format , add_data_validation
14,000

tables
set_table
1,900

charts
create_chart , delete_chart , add_sparklines , delete_sparklines
9,900

pivots
create_pivot_table , delete_pivot_table
4,600

slicers
add_slicer , delete_slicer
2,500

names
set_defined_name , delete_defined_name
900

notes
set_note , delete_note
500

images
insert_image , delete_image
800

vba
read_vba ; --allow-vba-write 사용 시: write_vba_module , delete_vba_module
1,900

CSV
import_csv 는 .csv 또는 .tsv 파일을 셀의 시트(없으면 생성)로 읽고,
export_csv 는 범위를 CSV로 씁니다. 둘 다 허용된 폴더 안에서 --max-cells 및
--max-file-mb 범위 내에서 작동하며 아무것도 실행하지 않습니다.

가져오기는 첫 레코드에서 구분자를 감지하고(또는 comma , semicolon , tab ,
pipe 사용) BOM이 있거나 없는 UTF-8, UTF-16, cp1252 를 읽습니다. 인용된 필드와 그 안의
줄바꿈은 유지됩니다.
필드는 Excel 가져오기처럼 형식이 지정됩니다: 숫자( 1,234.50 , 12% ; 소수점 쉼표의 경우
decimal), TRUE / FALSE 및 ISO 날짜( 2026-01-31 , 2026-01-31 09:30 )는 값이 됩니다.
Excel이 변경할 텍스트는 텍스트로 유지됩니다: 선행 0( 007 ), 15자리 초과, 선행 + ,
그리고 01/02/2026 같은 숫자 날짜는 지정한 date_order ( dmy 또는 mdy )에서만 읽힙니다.
as_text 는 모든 필드를 텍스트로 유지합니다.
필드는 절대 수식이 아닙니다. = , + , - 또는 @ 로 시작하는 텍스트는 Excel의 인용
접두사와 함께 텍스트로 저장되므로 셀을 편집해도 실행되지 않습니다. -5 같은 숫자는 숫자입니다.
내보내기는 원시 값(전체 정밀도, ISO 날짜)을 쓰거나, formatted 를 사용하면 Excel이
표시하는 값을 씁니다. = , + , - 또는 @ 로 시작하는 텍스트 셀에는 ' 접두사가 붙습니다
( escape_formulas , 기본값 켜짐). 따라서 파일을 여는 스프레드시트가 이를 실행하지 않습니다.
숫자에는 절대 접두사가 붙지 않습니다.
날짜/시간은 2026-01-31T09:30:00 으로 쓰이며, Excel은 이를 텍스트로 엽니다. Excel용으로는
formatted 를 사용하세요.
BOM에는 encoding: utf-8-sig 를 사용하세요. Excel이 UTF-8 파일을 더블클릭으로 열 때
악센트를 표시하려면 필요합니다. 줄은 CRLF로 끝납니다.

모든 매개변수는 TOOLS.md 에 문서화되어 있습니다. 매개변수는 모든 도구에서 같은 의미입니다:

Parameter
Meaning

path , sheet
워크북과 워크시트

range , at
셀 블록( A1:D20 )과 그곳에 배치되는 모든 것(쓰인 값, 복사본, 차트, 이미지, PivotTable, 슬라이서)의 왼쪽 위 셀

source
Wher…