1C OData MCP
Read-only MCP server for 1C:Enterprise via OData with metadata and query builder tools.
Open source Open in the app JSON README (API)
About
Read-only MCP server for 1C:Enterprise via OData with metadata and query builder tools.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- alexgrebeshok-coder
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Last push
- 2026-08-07T13:54:15Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.alexgrebeshok-coder/onec-odata-mcp
README
# onec-odata-mcp
[](https://www.npmjs.com/package/onec-odata-mcp)
[](https://github.com/modelcontextprotocol/registry)
[](./LICENSE)
## Подключи 1С к Claude за 5 минут
Даёт Claude (Desktop, Code, любой MCP-клиент) доступ на чтение к базе 1С:Предприятие через стандартный OData. Вместо выгрузки в Excel или ручного написания OData-урлов — спрашиваешь по-русски, получаешь структурированные данные из справочников и документов.
Работает с любой конфигурацией 1С, где опубликован OData (Бухгалтерия, ERP, Управление торговлей, самописные конфигурации).
> 📸 TODO: скриншот/видео 5-минутной настройки — добавить после первого прогона с реальной базой.
### Шаг 1 — установка
Ничего ставить локально не нужно, `npx` подтянет пакет при первом запуске:
**One-liner (after npm publish):**
```bash
npx -y onec-odata-mcp
```
Set `ONEC_BASE_URL`, `ONEC_USERNAME`, and `ONEC_PASSWORD` in your MCP client config (see below).
**From source:**
```bash
npx -y onec-odata-mcp
```
(Для разработки из исходников: `npm install && npm run build`.)
### Шаг 2 — подключи к Claude
**Вариант А — командой `claude mcp add` (Claude Code):**
```bash
claude mcp add onec-odata \
-e ONEC_BASE_URL=https://1c.example.com/your_db/odata/standard.odata \
-e ONEC_USERNAME=odata_user \
-e ONEC_PASSWORD=your_password \
-- npx -y onec-odata-mcp
```
**Вариант Б — вручную в `claude_desktop_config.json`** (Claude Desktop: Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"onec-odata": {
"command": "npx",
"args": ["-y", "onec-odata-mcp"],
"env": {
"ONEC_BASE_URL": "https://1c.example.com/your_db/odata/standard.odata",
"ONEC_USERNAME": "odata_user",
"ONEC_PASSWORD": "your_password"
}
}
}
}
```
Готовый сниппет лежит в [`examples/claude_desktop_config.json`](./examples/claude_desktop_config.json).
Опционально: `ONEC_DATABASE` (подсказка имени базы), `ONEC_METADATA_CACHE_TTL_MS` (TTL кэша метаданных, по умолчанию 1 час), `ONEC_WRITABLE=true` (разрешить реальную запись через `odata_write`; по умолчанию false). Либо вместо переменных окружения — JSON-файл `~/.onec-odata/onec-config.json` с полями `baseUrl`, `username`, `password` (и опционально `"writable": true`), путь к которому задаётся через `ONEC_CONFIG_PATH`.
### Шаг 3 — первый запрос
Перезапусти Claude и спроси:
> «Какие справочники и документы есть в базе 1С?»
Claude вызовет `odata_list_entities`, увидит список и дальше сам подберёт нужные инструменты под конкретный вопрос — без знания синтаксиса OData с твоей стороны.
Больше готовых промптов — в [`examples/prompts.md`](./examples/prompts.md).
## Инструменты
| Инструмент | Что делает | Пример вопроса |
|---|---|---|
| `odata_config` | Проверяет статус подключения и настройки | «Проверь, подключена ли 1С» |
| `odata_list_entities` | Список всех доступных OData-сущностей | «Какие справочники и документы есть в базе?» |
| `odata_metadata` | Типы и наборы сущностей из `$metadata` (кэш, TTL 1ч) | вызывается автоматически перед сложными запросами |
| `odata_explain_entity` | Поля, типы, ключи, связи конкретной сущности | «Какие поля у справочника Контрагенты?» |
| `odata_build_query` | Строит и проверяет `$filter`/`$select`/`$orderby` из структурированных параметров запроса | вызывается автоматически — Claude сам переводит «за июнь» в даты, тул собирает и валидирует фильтр |
| `odata_query` | Запрос к сущности с готовыми OData-параметрами | «Покажи остатки по счёту 51 за июнь» |
| `odata_count` | Количество записей, опционально с фильтром | «Сколько контрагентов зарегистрировано в этом году?» |
| `odata_write` | Создание/изменение/удаление сущности (POST/PATCH/DELETE) | «Создай контрагента…» — сначала dry-run-превью |
| `odata_financial_summary` | Автообнаружение типовых финансовых сущностей + счётчики | «Дай сводку по счетам, реализациям и контрагентам» |
Обычно агент сам комбинирует `odata_build_query` → `odata_query`/`odata_count`, тебе достаточно спросить своими словами.
## Безопасность
- **По умолчанию только чтение.** Флаг `writable` в конфиге базы (env `ONEC_WRITABLE=true` / `"writable": true` в `~/.onec-odata/onec-config.json`) по умолчанию **false**. Без него реальные `POST`/`PATCH`/`DELETE` не уходят в 1С.
- **Запись — только через `odata_write`.** У инструмента `dryRun` по умолчанию **true**: всегда сначала превью `{dryRun: true, wouldExecute: …}` без сетевого вызова. Реальная запись требует **и** `writable: true` на этой базе, **и** явного `dryRun: false`.
- **Пароль** передаётся Basic Auth (base64 в заголовке каждого запроса — как требует OData) и хранится либо в env-переменных конфига твоего MCP-клиента (рекомендуется), либо в локальном файле `~/.onec-odata/onec-config.json`. Сервер не логирует и не возвращает пароль в ответах инструментов.
- **Поля-секреты** (`password`, `token`, `apikey`, `secret` и т.п. в названиях) автоматически исключены из подсказок «возможно, вы имели в виду» (`src/query/fuzzy.ts`), чтобы агент не подсвечивал их случайно.
- **Рекомендация:** заведи в 1С отдельного OData-пользователя с ролью только на чтение для обычной работы; writable-учётку и `ONEC_WRITABLE=true` включай только осознанно.
## Требования
- Node.js ≥ 18
- 1С:Предприятие с опубликованным OData-интерфейсом (веб-публикация → `standard.odata`)
## Разработка
```bash
npm install
npm run build # type-check + сборка в dist/
npm test
```
Детали и правила вклада — в [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
MIT
---
## English (short)
MCP server giving Claude (or any MCP client) access to a 1C:Enterprise database via its standard OData endpoint. **Read-only by default** (`writable: false`); writes go through `odata_write` and always dry-run first unless you explicitly enable `writable: true` and pass `dryRun: false`. No spreadsheet exports, no hand-written OData URLs — ask in natural language, get structured data from catalogs and documents.
```bash
npx -y onec-odata-mcp
```
Configure via `ONEC_BASE_URL` / `ONEC_USERNAME` / `ONEC_PASSWORD` env vars (see the Russian quick-start above for `claude mcp add` and `claude_desktop_config.json` snippets — the JSON is language-agnostic). Optional: `ONEC_WRITABLE=true` to allow real writes. Published on npm as [`onec-odata-mcp`](https://www.npmjs.com/package/onec-odata-mcp) and listed in the official MCP Registry as `io.github.alexgrebeshok-coder/onec-odata-mcp`.