ExcelMCP

Живой интеллектуальный слой для работы с Excel, предназначенный для AI-агентов. Укажите папку OneDrive, и ваш агент сможет задавать вопросы об этих таблицах на обычном английском языке, опираясь на текущие данные.

Решаемая проблема

Большинство интеграций с электронными таблицами работают по принципу копирования ваших данных в другое место. Они загружают книгу, разбивают на фрагменты, встраивают значения ячеек и сохраняют всё в векторной базе данных. С этого момента ваш агент отвечает на вопросы, основываясь на снимке данных. Кто-то обновляет складскую ведомость в 9 утра, а агент всё ещё цитирует данные за вторник.

ExcelMCP разделяет проблему на две части.

Структура кэшируется. Имена файлов, имена листов, заголовки столбцов, расположение строки заголовка, какие столбцы содержат даты, как листы связаны между собой — плюс небольшая выборка уникальных меток для каждого столбца с низкой кардинальностью, что позволяет правильно маршрутизировать запросы между сотнями почти одинаковых листов. Это редко меняется, хранить дёшево, и именно это нужно агенту, чтобы знать что запрашивать. (Выборка меток — единственное место, где структура касается значений; точные границы описаны в разделе Что попадает на диск.)

Данные никогда не кэшируются. Каждый вызов инструмента, возвращающий число, обращается к Microsoft Graph API и получает данные в реальном времени. Нет кэша данных, который мог бы устареть, нет задачи синхронизации, которая могла бы отстать, и ни один ответ никогда не обслуживается с диска.

Каждый ответ содержит временную метку metadata.fetched_at и флаг is_cached: false, чтобы модель могла видеть, что она смотрит на свежие данные.

Related MCP server: Microsoft 365 MCP Server

Как это работает

Вопрос на естественном языке встраивается, сопоставляется с описаниями листов по косинусному сходству, затем переранжируется по лексическому совпадению с именами столбцов и выборочными значениями — это позволяет сохранять осмысленность маршрутизации, когда двадцать книг используют одну схему. Эти листы (и только они) загружаются в реальном времени. Фильтрация и агрегация затем выполняются в pandas на только что загруженном фрейме. Вопросы с одним значением обходят конвейер строк целиком: lookup читает один ключевой столбец и одну строку и возвращает ячейку с её происхождением.

Требования

• Python 3.10 или новее

• Учётная запись Microsoft 365 с OneDrive

• 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 .

Нет этапа компиляции и не нужно собирать нативные расширения. Векторный поиск работает на основе косинусного сканирования NumPy, а не hnswlib, специально для того, чтобы pip install работал на машине без набора инструментов C++.

Настройка

Запустите мастер один раз:

excelmcp-setup

Он проводит через четыре шага:

1. Вход через Microsoft device-flow. Вы получаете код, вставляете его в браузер, кэш токенов сохраняется в ~/.excelmcp/token.json с правами 0600.

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,
)

Поддерживаемые операторы условий, все объединяются по И:

Несуществующее имя столбца или оператор вызывает ошибку, а не молча возвращает ноль строк, что является типом отказа, при котором агент уверенно сообщает неверную информацию. Когда условия законно не дают совпадений, ответ содержит zero_match_diagnostics — что каждое условие совпало само по себе, плюс до двадцати значений, фактически присутствующих в проблемном столбце — так что почти совпадение исправляется, а не сообщается как «нет данных».

Запросить одно число за один вызов:

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 в других. Проверьте sheet_name_variants в get_workspace_graph перед агрегацией, чтобы увидеть эту фрагментацию заранее.

Руководство для агента

Установка сервера — это только половина дела. Папка agents/ охватывает другую половину: как подсказывать агенту, у которого есть эти инструменты, как подключать его к каждому хосту и что автоматизировать после того, как всё заработает.

Встроенные ограничения сервера

Сервер поставляется с набором правил работы в инструкциях MCP, которые модель-хост читает перед первым вызовом. Они существуют, потому что именно так LLM ошибается в вопросах по электронным таблицам:

• Никогда не предполагайте имя файла, листа или столбца. Узнавайте его из графа.

• Никогда не суммируйте числа из разных файлов в уме. Вызывайте cross_file_aggregate и позволяйте инструменту сделать это.

• Никогда не используйте openpyxl, pandas.read_excel или локальную файловую систему. Файлы находятся не на этой машине.

• Никогда не суммируйте столбец количества в данных транзакционного типа «сырыми» — используйте derive с явным указанием типов транзакций.

• Столбцы с датами поступают в виде строк ISO-8601, уже преобразованных из серийных номеров сервером. Никогда не выполняйте арифметику с серийными номерами вручную.

• Для получения одного значения вызывайте lookup и ссылайтесь на возвращаемый источник; выводите результаты ambiguous и conflict вместо выбора значения.

• Проверяйте поля truncated и total_matched, прежде чем утверждать, что результат полон.

Хосты, игнорирующие инструкции сервера, и пользовательские агенты, которые вы создаёте сами, должны иметь это указано в собственном промпте. См. agents/system-prompt.md.

Конфигурация

Встроенный идентификатор клиента — это публичный клиент, используемый для потока с кодом устройства. Он не содержит секрета, виден в каждом запросе аутентификации по замыслу и безопасен для хранения в этом репозитории. Замените его на собственную регистрацию приложения, если хотите, чтобы экран согласия отображал название вашей организации.

Что попадает на диск

~/.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 там является наилучшим усилием, а реальная защита — это ACL по умолчанию для каждого пользователя на %USERPROFILE%. В 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

Участие в разработке

Приветствуются issues и pull request'ы. Если вы добавляете поддержку другого агента, agents.py — единственный файл, который вам нужно трогать: добавьте AgentSpec с путём к конфигурации, формой записи и подсказкой для обнаружения.

Лицензия

MIT. См. LICENSE.