ExcelMCP

AI 에이전트를 위한 실시간 Excel 인텔리전스 레이어. OneDrive 폴더를 가리키면 에이전트가 현재 있는 숫자에 대해 평범한 영어로 스프레드시트에 질문할 수 있습니다.

이 도구가 해결하는 문제

대부분의 스프레드시트 통합은 데이터를 다른 곳에 복사하는 방식으로 작동합니다. 통합 문서를 수집하고, 청크로 나누고, 셀 값을 임베딩한 후, 전체를 벡터 데이터베이스에 저장합니다. 그 순간부터 에이전트는 스냅샷에 대한 질문에 답하게 됩니다. 누군가 오전 9시에 재고 시트를 업데이트해도 에이전트는 화요일 숫자를 인용하고 있습니다.

ExcelMCP는 문제를 두 가지로 나눕니다.

구조는 캐시됩니다. 파일 이름, 시트 이름, 열 머리글, 머리글 행이 시작되는 위치, 어떤 열이 날짜를 보유하는지, 시트가 서로 어떻게 관련되는지 — 또한 낮은 카디널리티 열당 고유 레이블의 작은 샘플도 포함됩니다. 이는 수백 개의 거의 동일한 시트에서 라우팅을 가능하게 하는 요소입니다. 이것은 거의 변경되지 않으며 저장 비용이 저렴하고, 에이전트가 무엇을 요청할지 알기 위해 필요한 정보입니다. (샘플링된 레이블은 구조가 값에 닿는 유일한 지점입니다. 정확한 경계는 디스크에 저장되는 내용에 설명되어 있습니다.)

데이터는 절대 캐시되지 않습니다. 숫자를 반환하는 모든 도구 호출은 Microsoft Graph API로 나가서 실시간으로 가져옵니다. 오래된 데이터 캐시, 뒤처지는 동기화 작업, 디스크에서 제공되는 답변은 없습니다.

모든 응답에는 metadata.fetched_at 타임스탬프와 is_cached: false 플래그가 포함되어 있어 모델이 대역 내에서 최신 데이터를 보고 있음을 알 수 있습니다.

Related MCP server: Microsoft 365 MCP Server

작동 방식

자연어 질문이 임베딩되고, 코사인 유사도로 시트 설명과 매칭된 후, 열 이름 및 샘플링된 값과의 어휘적 중복으로 재순위화됩니다. 이는 20개의 통합 문서가 하나의 스키마를 공유할 때 라우팅을 의미 있게 유지하는 방법입니다. 해당 시트들만 실시간으로 가져옵니다. 그런 다음 필터링과 집계는 새로 가져온 프레임에서 pandas로 이루어집니다. 단일 값 질문은 행 파이프라인을 완전히 건너뜁니다. lookup은 하나의 키 열과 하나의 행을 읽고, 출처와 함께 셀을 반환합니다.

요구 사항

• Python 3.10 이상

• OneDrive가 있는 Microsoft 365 계정

• uv 또는 원한다면 일반 pip

설치

저장소 루트에서:

git clone https://github.com/Karunya-Muddana/ExcelMCP.git
cd ExcelMCP

uv sync      # install dependencies
uv build     # build the wheel
pip install dist/excelmcp-0.3.0-py3-none-any.whl

또는 빌드 없이 소스에서 직접 설치:

pip install .

컴파일러 단계나 네이티브 확장 빌드가 없습니다. 벡터 검색은 hnswlib 대신 NumPy 코사인 스캔으로 실행되므로, C++ 툴체인이 없는 머신에서도 pip install이 작동합니다.

설정

마법사를 한 번 실행합니다:

excelmcp-setup

네 가지를 안내합니다:

1. Microsoft 장치 흐름 로그인. 코드를 받아 브라우저에 붙여넣으면 토큰 캐시가 0600 권한으로 ~/.excelmcp/token.json에 저장됩니다.

2. 인덱싱할 OneDrive 폴더(예: /ERP).

3. 해당 폴더의 모든 .xlsx 파일을 스캔하여 구조 그래프와 임베딩을 구축합니다.

4. 머신에 이미 설치된 AI 에이전트를 감지하고 선택한 에이전트에 대한 설정 항목을 작성합니다.

자동으로 설정할 수 있는 에이전트

기존 설정 파일은 수정되기 전에 백업됩니다. 에이전트가 목록에 없으면 마법사가 직접 붙여넣을 정확한 JSON 또는 TOML 블록을 출력합니다.

기타 마법사 명령어

excelmcp-setup list-agents           # show what was detected
excelmcp-setup install --only cursor # register with one agent, skip the rescan
excelmcp-setup doctor                # diagnose a broken install
excelmcp-setup uninstall             # remove ExcelMCP from every agent config
excelmcp-setup --folder /ERP --yes   # fully non-interactive
excelmcp-setup --dry-run             # print the changes, write nothing

에이전트에 노출되는 도구

두 구조 도구는 로컬 그래프를 읽기 때문에 무료이며 즉시 실행됩니다. 실시간으로 표시된 모든 것은 매 호출마다 API로 이동합니다.

사용법

서버가 등록되면 대부분 평소처럼 에이전트와 대화하면 됩니다. 내부적으로는 다음과 같은 호출을 수행합니다.

먼저 방향을 잡습니다. 에이전트는 열 이름을 추측하기 전에 항상 이 작업을 수행해야 합니다. 어떤 두 회사도 같은 방식으로 이름을 짓지 않기 때문입니다:

get_workspace_graph(folder_path="/ERP")

답이 어디에 있는지 모르는 상태에서 질문합니다:

query("what are the top 10 products by sales value", folder_path="/ERP")

알려진 시트를 필터링합니다:

filter_sheet(
    file_name="Inventory.xlsx",
    sheet="Stock",
    conditions={"Status": "Low", "Quantity": "<50"},
    folder_path="/ERP",
    sort_by="Quantity",
    limit=100,
)

지원되는 조건 연산자, 모두 AND로 결합됩니다:

존재하지 않는 열 이름이나 연산자는 오류를 발생시켜 자동으로 0행을 반환하지 않습니다. 이는 에이전트가 잘못된 것을 자신 있게 보고하게 만드는 실패 모드입니다. 조건이 정당하게 아무것도 일치하지 않으면 응답에 zero_match_diagnostics가 포함됩니다 — 각 조건이 자체적으로 일치시킨 내용과 문제가 있는 열에 실제로 있는 최대 20개의 값 — 따라서 근접 실패가 "데이터 없음"으로 보고되는 대신 수정됩니다.

한 번의 호출로 단일 수치를 요청합니다:

lookup(query="contracted rate for Titanium Dioxide under the BESTEX contract",
       folder_path="/Contracts")

답변은 출처(파일, 시트, 셀 주소, 일치된 행)와 신뢰도 필드와 함께 반환됩니다. 여러 개의 일치 행이 있으면 모든 행과 함께 ambiguous를 반환합니다. 시트 간에 불일치가 있으면 모든 버전과 값 없이 conflict를 반환합니다. 잘못 입력된 키는 퍼지 제안을 반환합니다. 이 도구는 절대 단순한 숫자를 반환하지 않습니다.

하나의 파일 내에서 그룹화하고 축소합니다:

aggregate(
    file_name="Sales.xlsx",
    sheet="Q1",
    group_by="Region",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
)

작업 공간의 모든 파일에서 동일한 시트를 합산합니다:

cross_file_aggregate(
    sheet="Q1",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
    conditions={"Status": "Closed"},
)

cross_file_aggregate는 파일별 분석과 함께 총계를 반환하며, 파일을 읽을 수 없는 경우 skipped_files와 정확한 시트 이름을 포함하지 않는 모든 파일에 대해 unmatched_files( did_you_mean 후보 포함)를 반환합니다. 이렇게 하면 부분 총계가 조용히 잘못되는 대신 명확하게 부분임을 알 수 있습니다. 여기에는 일부 파일에서 시트 이름이 Sales이고 다른 파일에서는 Sales 2024인 경우도 포함됩니다. 집계하기 전에 get_workspace_graph에서 sheet_name_variants를 확인하여 이러한 분열을 미리 확인하십시오.

에이전트 플레이북

서버를 설치하는 것은 쉬운 절반입니다. agents/ 폴더는 나머지 절반을 다룹니다: 이러한 도구를 가진 에이전트를 프롬프트하는 방법, 각 호스트에 연결하는 방법, 그리고 작동한 후에 자동화할 내용입니다.

서버에 내장된 안전장치

서버는 MCP 명령어에 일련의 운영 규칙을 포함하여 제공하며, 호스트 모델은 첫 번째 호출을 하기 전에 이를 읽습니다. 이 규칙들은 LLM이 스프레드시트 질문에 대해 특정 방식으로 오류를 범하기 때문에 존재합니다:

• 파일 이름, 시트 이름 또는 열 이름을 추정하지 마십시오. 그래프에서 찾으십시오.

• 여러 파일의 숫자를 머릿속으로 더하지 마십시오. cross_file_aggregate를 호출하여 도구가 처리하도록 하십시오.

• openpyxl, pandas.read_excel 또는 로컬 파일 시스템을 사용하지 마십시오. 파일은 이 머신에 없습니다.

• 트랜잭션 스타일 데이터에서 수량 열을 원시 합계로 계산하지 마십시오. 트랜잭션 유형을 명시하여 derive를 사용하십시오.

• 날짜 열은 서버에서 직렬 값에서 이미 변환된 ISO-8601 문자열로 도착합니다. 수동으로 직렬 산술을 수행하지 마십시오.

• 단일 수치의 경우 lookup을 호출하고 반환되는 출처를 인용하십시오. 값을 선택하는 대신 ambiguous 및 conflict 결과를 표시하십시오.

• 결과가 완전하다고 주장하기 전에 truncated 및 total_matched 필드를 확인하십시오.

서버 명령어를 무시하는 호스트와 직접 구축하는 커스텀 에이전트는 자체 프롬프트에 이를 명시해야 합니다. agents/system-prompt.md를 참조하십시오.

구성

내장 클라이언트 ID는 장치 코드 흐름에 사용되는 공용 클라이언트입니다. 비밀을 포함하지 않으며, 설계상 모든 인증 요청에 표시되며, 이 저장소에 있어도 안전합니다. 동의 화면에 조직 이름을 표시하려면 자체 앱 등록으로 교체하십시오.

디스크에 저장되는 내용

~/.excelmcp/
  token.json           MSAL token cache. Auth material only, written 0600.
  graph.json           Structure graph: item IDs, sheet names, column headers,
                       used-range dimensions, date column types, per-sheet
                       table regions, inferred and formula-declared
                       relationships — and sampled values (see below).
  vectors.npy          Embedded sheet descriptions for semantic routing.
  metadata.json        Labels and lexical terms tying each embedding to a sheet.
  relationships.yaml   Optional, written by you: declared join relationships.

0.3.0 기준, 캐시 없음 주장의 정직한 버전입니다. 데이터의 어떤 행, 셀 그리드, 또는 쿼리 가능한 값도 디스크에 저장되지 않습니다. 모든 답변은 항상 실시간 가져오기로 제공됩니다. 한 가지 의도적인 예외가 있습니다: graph.json은 샘플링된 값을 저장하며, 스캔 시점에 캡처된 낮은 카디널리티 열(클라이언트 이름, 상태, 자재 이름, 단위)당 최대 50개의 고유 텍스트 레이블을 저장합니다. 이 값들은 수백 개의 구조적으로 동일한 시트를 질문 라우팅 시 구별할 수 있도록, lookup이 모든 것을 다운로드하지 않고도 "BESTEX"가 포함된 시트를 찾을 수 있도록, 그리고 열 이름에서 가정하는 대신 값 중복에서 관계를 추론할 수 있도록 존재합니다. 이는 라우팅 증거이지 데이터 캐시가 아닙니다. 어떤 것도 이 값들로 질문에 답변하지 않으며, 작업 공간 스캔 시 전체를 새로 고칩니다. 그래프는 또한 시트별 구조 지문(헤더 열 및 사용된 범위 주소)을 드리프트 감지 목적으로만 저장하며, 0.3.0의 새로운 기능으로 영역 맵을 저장합니다: 시트의 자체 SUM/COUNT/AVERAGE 수식이 참조하는 범위와 교차 시트 수식이 읽는 주소에서 파생된 시트의 각 테이블 본문 행 범위입니다. 이는 행 번호와 셀 주소이지 내용이 아닙니다. 값을 읽어 생성되지 않습니다. 영역의 label(있는 경우)은 샘플링된 값과 함께 두 번째 의도적인 예외입니다: 영역 바로 위의 섹션 배너 셀에서 읽은 몇 단어("NAPHTHALENE", "OLEUM 65%")로, 모델이 행 번호에서 추측하는 대신 어떤 테이블을 의미하는지 이름을 지정할 수 있도록 유지됩니다. 이는 시트 레이아웃을 설명하는 구조적 메타데이터이지 행 데이터가 아닙니다. 이는 샘플링된 값이 이미 그리는 것과 동일한 구분입니다. 이 중 어떤 것이든 디스크에 저장하기 싫다면 해당 폴더를 스캔하지 마십시오. 경계를 확인하려면 graph.json이 작고 읽을 수 있으므로 직접 확인하십시오.

Windows에서 os.chmod는 읽기 전용 비트만 전환하므로 0600 모드는 최선의 노력이며 실제 보호는 %USERPROFILE%의 기본 사용자별 ACL입니다. macOS 및 Linux에서는 임시 파일에 내용이 기록되기 전에 모드가 적용되므로 토큰이 세계에서 읽을 수 있는 상태로 잠시 존재하지 않습니다.

테스트

# offline unit tests, no network and no credentials required
pytest tests/test_unit.py

# live integration tests against a workspace you have already scanned, opt in
EXCELMCP_TEST_FOLDER=/ERP pytest tests/test_live_integration.py -v

통합 테스트 스위트는 EXCELMCP_TEST_FOLDER가 설정되지 않으면 자체를 건너뛰므로, 일반 pytest 실행은 오프라인 상태를 유지합니다.

프로젝트 레이아웃

agents/           prompts, host guides, and schedulable routines
auth.py           MSAL device flow, token cache, proactive refresh
graph_client.py   Graph API wrapper, 429 backoff, shared concurrency gate
structure.py      Structure discovery, value sampling, relationship inference
embeddings.py     FastEmbed vectors, NumPy cosine search, lexical rerank
query_engine.py   Conditions, live fetch, aggregation, joins, derive
lookup.py         Single-cell lookup pipeline and get_cell
ranges.py         A1-notation range arithmetic
main.py           FastMCP tool definitions and server entry point
cli.py            Setup wizard, agent detection, config writing
agents.py         Per agent config formats and file locations
storage.py        Atomic writes, stderr logging, config directory handling

기여

이슈 및 풀 리퀘스트를 환영합니다. 다른 에이전트에 대한 지원을 추가하는 경우, agents.py만 수정하면 됩니다: 구성 경로, 항목 형태 및 감지 힌트와 함께 AgentSpec을 추가하십시오.

라이선스

MIT. LICENSE를 참조하십시오.