mcp-excel

Model Context Protocol 서버로, Claude Code(또는 모든 MCP 클라이언트)가 Excel 통합 문서에 대해 전체 읽기/쓰기 액세스 권한을 갖도록 합니다: 시트, 셀 범위, 구조화된 표, 수식, 서식, 통합 문서 간 참조를 지원합니다. ExcelJS를 사용하여 디스크의 실제 .xlsx 파일을 읽고 씁니다. Excel 복사본, Microsoft 계정, 클라우드 서비스가 필요 없습니다.

로컬에서 stdio 하위 프로세스로 실행되거나 HTTP/SSE 서비스로 실행됩니다(하나의 인스턴스를 LAN을 통해 Docker로 데스크톱 클라이언트와 공유할 때 유용).

상태: 11개 도구, stdio + SSE 전송, npm 외 외부 종속성 없음. 라이선스: MIT.

도구

모든 파일 경로 인수는 서버의 작업 디렉터리를 기준으로 path.resolve()로 확인되므로 절대 경로가 가장 안전합니다. Docker(SSE) 모드에서는 경로가 마운트된 /data 볼륨(아래 참조)을 기준으로 컨테이너 내부에서 확인됩니다.

Related MCP server: mcp-xlsx-server

요구 사항

• Node.js 18 이상(stdio 모드), 또는

• Docker(SSE / 공유 인스턴스 모드)

설정: Claude Code(stdio, 로컬)

클론 및 설치:

git clone https://bitbucket.org/corvalon/mcp-excel.git
cd mcp-excel
npm ci

서버를 등록합니다. CLI로 추가하거나:

claude mcp add excel -- node /absolute/path/to/mcp-excel/index.js

또는 Claude Code 구성(~/.claude.json)에 수동으로 추가합니다:

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-excel/index.js"]
    }
  }
}

Claude Code를 다시 시작합니다. 도구는 mcp__excel__* 접두사 아래에 나타납니다.

설정: Claude Desktop(stdio, 로컬)

Claude Desktop의 구성(Settings > Developer > Edit Config, claude_desktop_config.json이 열림)에 동일한 블록을 추가합니다:

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-excel/index.js"]
    }
  }
}

저장하고 다시 시작합니다. 망치/도구 아이콘이 나타나면 서버가 연결된 것입니다.

설정: Docker(SSE, 공유 인스턴스)

네트워크의 모든 MCP 클라이언트가 SSE를 통해 도달할 수 있는 컨테이너 하나를 실행합니다. Node.js가 없는 머신에서 Excel 파일을 구동할 때 유용합니다.

1. 통합 문서가 있는 폴더를 컨테이너에 마운트하고 시작합니다:

   MCP_EXCEL_DATA_DIR=/path/to/your/spreadsheets docker compose up -d --build

   compose 파일은 해당 폴더를 컨테이너 내부의 /data로 마운트하고 포트 3001에서 수신 대기합니다.

2. 클라이언트 구성에 SSE 엔드포인트를 추가합니다(클라이언트가 다른 머신에 있는 경우 호스트를 컨테이너 호스트의 LAN IP로 바꿉니다):

   {
     "mcpServers": {
       "excel": {
         "url": "http://localhost:3001/sse"
       }
     }
   }

3. 경로는 컨테이너 내부에서 확인되므로 /data 마운트를 기준으로 파일을 지정합니다. MCP_EXCEL_DATA_DIR이 ~/spreadsheets이면 도구 호출에서 ~/spreadsheets/2025/Budget.xlsx는 /data/2025/Budget.xlsx입니다.

다른 호스트의 클라이언트가 SSE로 연결할 때 MCP_ALLOWED_HOSTS를 설정하여 서버가 요청을 수락하도록 합니다. docker-compose.yml 옆에 .env 파일을 만듭니다:

MCP_ALLOWED_HOSTS='localhost,127.0.0.1,::1,192.168.1.50,my-host.local'

컨테이너 관리:

docker compose up -d --build   # start / rebuild after code changes
docker compose down            # stop
docker compose logs -f         # tail logs

http://<host>:3001/health에서 상태 확인을 사용할 수 있습니다.

구성

보안

이 서버는 실제 파일을 읽고 쓰며, SSE 모드에서는 네트워크 포트를 엽니다. 신뢰할 수 있는 로컬 도구로 취급하고 인터넷에 노출되는 서비스로 취급하지 마십시오.

• 파일 액세스. 도구 호출은 서버 프로세스가 도달할 수 있는 모든 .xlsx 경로를 읽거나 쓸 수 있습니다. stdio 모드에서는 전체 파일 시스템입니다. Docker(SSE) 모드에서는 마운트된 /data 볼륨으로 범위가 제한되므로 Docker가 액세스를 제한하는 더 안전한 방법입니다.

• SSE에는 인증이 없습니다. HTTP/SSE 엔드포인트는 0.0.0.0에서 수신 대기하며 호출자를 인증하지 않습니다. 신뢰할 수 있는 LAN에서만 실행하고 MCP_ALLOWED_HOSTS(Host 헤더 허용 목록)와 자체 방화벽으로 도달할 수 있는 대상을 제한하십시오. 포트 3001을 공개 인터넷에 노출하지 마십시오.

• 수식은 데이터이지 코드가 아닙니다. ExcelJS는 수식 문자열을 씁니다. 매크로나 VBA를 실행하지 않으므로 생성된 통합 문서를 열어도 이 서버의 코드는 실행되지 않습니다.

예시 프롬프트

• "Category, Budget, Actual, Difference 열이 있는 새 예산 통합 문서를 만들어."

• "Sales.xlsx의 데이터를 읽고 지역별 합계를 요약해."

• "Q1 시트의 B열 맨 아래에 SUM 수식을 추가해."

• "이 데이터로 합계 행이 있는 서식 있는 표를 만들어."

• "Budget.xlsx의 월별 합계를 Report.xlsx의 Summary 시트로 가져와."

참고 사항 및 주의점

권한. 하나의 와일드카드로 11개 도구 모두를 허용합니다: mcp__<key>__*를 허용하세요. 여기서 <key>는 서버를 등록한 이름입니다. excel로 등록했다면 mcp__excel__*입니다. 도구를 개별적으로 나열할 필요가 없습니다.

알 수 없는 매개변수는 거부됩니다(1.1.0부터). 잘못 입력된 인수 이름은 키를 명명하는 -32602 unrecognized_keys로 실패하며, 모든 도구는 additionalProperties: false를 게시합니다. 이전 버전은 오타를 조용히 무시하고 기본값으로 실행되어 잘못된 데이터를 자신 있게 반환했습니다.

수식은 저장되며 계산되지 않습니다. 이 서버는 수식 텍스트를 씁니다. 결과를 계산하지 않습니다. 수식 셀을 다시 읽으면 파일이 Excel 또는 LibreOffice에서 열리고 저장되어 캐시된 결과가 채워질 때까지 =SUM(A1:A2) (result: not calculated)를 반환합니다. 계산된 합계가 필요하면 원본 셀을 읽고 직접 합산하거나, 먼저 스프레드시트 응용 프로그램을 통해 파일을 왕복시키십시오.

제한 사항

현재 어떤 도구로도 노출되지 않는 기능:

• 시트 중간에 행/열 삽입 또는 삭제

• 정의된 이름 생성 또는 편집

• 표와 정의된 이름 구분

이러한 경우 스프레드시트 라이브러리로 파일을 직접 구동하십시오. Python에서는 openpyxl이 세 가지 모두를 다룹니다. 수식을 보존하려면 load_workbook(path, data_only=False)로 로드하십시오. data_only=True는 위의 이유로 None일 수 있는 캐시된 값을 반환하기 때문입니다.

라이선스

MIT (c) 2026 Corvalon.