io.github.theYahia/1c-rest-mcp

Official

by theYahia · TypeScript

1c-rest-mcp

MCP server for 1C Enterprise — ERP catalogs, documents via REST API (Russia)

Accesses 1C Enterprise ERP catalogs and documents via REST API.

Topics

claudemcpmodel-context-protocolrussian-apitypescripterp1cai-agentsanthropicemerging-marketsmcp-serversrussia

README.md13 KBView on GitHub

@theyahia/1c-rest-mcp

MCP server for 1C:Enterprise REST API via OData 3.0 — catalogs, documents, registers, accounting, constants, reports, batch ops & change-tracking + metadata discovery. 32 tools across 11 modules. HTTP Basic auth. Stdio + Streamable HTTP transports.

Migrating from v1.x

If you starred or used v1.x, the v2.0.0 release introduces a few breaking changes:

HTTP transport env var renamed: PORT=3000 → HTTP_PORT=3000.
Removed separate HTTP binary: 1c-rest-mcp-http is gone. Use 1c-rest-mcp --http or HTTP_PORT=3000 1c-rest-mcp instead.
Single bin entrypoint: dist/http.js is no longer published.
Internal client: now extends @theyahia/mcp-core's BaseHttpClient with BasicAuthStrategy. The exported functional API (oneCGet/oneCPost/oneCPatch/buildODataPath) is unchanged, so tool code keeps working.
Tool errors: now returned as MCP-spec CallToolResult with isError: true (via withErrorHandling from @theyahia/mcp-core). Compatible with all MCP clients.

Tool names, arguments, return formats, and the ONEC_* env vars are unchanged.

Tools (32)

Tools are grouped into modules. All are registered by default; the ONEC_SERVICES env var filters which optional modules load (discovery meta is always on). See Environment Variables.

Discovery — `meta` (always enabled)

Tool	Description
`list_entities`	List all available 1C OData entities (catalogs / documents / registers / reports). Use this first when working with an unfamiliar database.
`get_document_by_number`	Locate a 1C document by its number (e.g. invoice ТД-00123 dated 2026-03-01). Convenience wrapper over `$filter`.
`get_metadata`	Return the raw OData `$metadata` (EDMX/XML) describing every entity, field and type.
`describe_entity`	List an entity's fields by inspecting one sample record (`$top=1`) — cheaper than full `$metadata`.

Catalogs — `catalogs`

Tool	Description
`get_catalogs`	Read 1C catalog data. Supports `$filter`, `$select`, `$orderby`, `$top`, `$skip`.
`create_catalog_item`	Create a new catalog item via OData POST (e.g. add a Контрагент or Номенклатура).
`update_catalog_item`	Update a catalog item via OData PATCH (by `Ref_Key` GUID).

Documents — `documents`

Tool	Description
`get_documents`	Read 1C documents with full OData filtering.
`create_document`	Create a new document via OData POST.
`update_document`	Update an existing document via OData PATCH (by `Ref_Key` GUID).
`post_document`	Post (провести) a document via the OData bound action `Post()`. `operational` toggles оперативное проведение.
`unpost_document`	Unpost (отменить проведение) a document via `Unpost()`.
`delete_document`	Physically delete a document via OData DELETE. Prefer `set_deletion_mark` for a recoverable soft delete.
`get_document_lines`	Read a document's tabular section (строки, e.g. Товары) by `Ref_Key` via `$expand`. Section name is config-specific — discover via `get_metadata`/`describe_entity`.

Registers — `registers`

Tool	Description
`get_register`	Read information or accumulation register data.
`write_information_register`	Write a record into an independent information register (POST on `InformationRegister_*`).
`get_accumulation_balance`	Accumulation-register balances (остатки) via the OData virtual method `Balance(Period=…,Condition=…)`.

Accounting — `accounting`

Tool	Description
`get_accounting_register`	Read accounting-register records (`AccountingRegister_*`, e.g. Хозрасчетный — проводки).

Constants — `constants`

Tool	Description
`get_constant`	Read a 1C constant value (`Constant_*`).
`set_constant`	Write a 1C constant value via OData PATCH (`Value` field).

Shortcuts — `shortcuts`

Tool	Description
`find_by_description`	Fuzzy-find items by a substring of `Description` (OData `substringof`).
`get_by_key`	Fetch a single record by its `Ref_Key` (GUID).
`count_entities`	Count records of an entity (`$inlinecount`, `$top=0`) with an optional filter.
`set_deletion_mark`	Set/clear the `DeletionMark` on a catalog item or document (recoverable soft delete).
`get_recent_documents`	Most recent documents of a type, ordered by `Date desc` (optionally posted only).

Reports — `reports`

Tool	Description
`get_report`	Get a 1C report from a relative HTTP service URL (`/hs/...`). Restricted to the configured `ONEC_BASE_URL` origin.

Generic OData — `odata`

Tool	Description
`odata_query`	Run an arbitrary OData 3.0 query. Supports `$filter`, `$select`, `$expand`, `$orderby`, `$top`, `$skip`, `$inlinecount`.

Batch — `batch`

1C has no native OData $batch endpoint. These tools dispatch N requests in parallel (bounded concurrency) and report per-item success/failure — a partial failure never aborts the batch.

Tool	Description
`batch_create_documents`	Create N documents (1..100) of one type in parallel.
`batch_update_catalog_items`	PATCH N catalog items by `Ref_Key` in parallel.
`batch_query`	Run N OData GET queries (1..50) in parallel; combine results client-side.

Change tracking — `changes`

1C has no webhooks / event subscriptions — only polling.

Tool	Description
`poll_changes_since`	Pull rows modified since a timestamp cursor (`$filter` on a date field); returns a `next_cursor` for the next poll.
`list_subscriptions`	Explicit no-op documenting the absence of 1C webhooks; redirects to `poll_changes_since`.

Note on write/posting tools. post_document/unpost_document/delete_document, get_accumulation_balance (virtual Balance) and write_information_register follow the 1C:Enterprise OData 3.0 spec. URL/parameter shapes should be validated against your specific 1C configuration's $metadata (use get_metadata) before relying on them in production.

Prompts

The server ships three MCP prompts — guided multi-tool workflows your client can invoke directly (they travel with the npm package, no separate skill install):

Prompt	Arguments	What it does
`inventory-database`	—	`list_entities` → group by prefix → `count_entities` → `describe_entity` to map an unfamiliar base.
`find-and-post-document`	`query`, `document_type?`	Finds a document, shows its fields + lines, then posts it only after explicit human confirmation.
`reconcile-balances`	`register_name`, `period?`	Compares `get_accumulation_balance` (остатки) against `get_register` movements and reports discrepancies.

Quick Start

Claude Desktop

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "1c": {
      "command": "npx",
      "args": ["-y", "@theyahia/1c-rest-mcp"],
      "env": {
        "ONEC_BASE_URL": "http://server:8080/base",
        "ONEC_LOGIN": "your_login",
        "ONEC_PASSWORD": "your_password"
      }
    }
  }
}

Cursor / Windsurf

Same configuration block under mcpServers in the IDE's MCP settings.

VS Code (Copilot)

Add to .vscode/mcp.json:

json

{
  "servers": {
    "1c": {
      "command": "npx",
      "args": ["-y", "@theyahia/1c-rest-mcp"],
      "env": {
        "ONEC_BASE_URL": "http://server:8080/base",
        "ONEC_LOGIN": "your_login",
        "ONEC_PASSWORD": "your_password"
      }
    }
  }
}

Streamable HTTP transport

For remote/multi-tenant deployments, run as an HTTP server:

bash

HTTP_PORT=3000 \
ONEC_BASE_URL=http://server:8080/base \
ONEC_LOGIN=admin \
ONEC_PASSWORD=secret \
npx @theyahia/1c-rest-mcp
# or: npx @theyahia/1c-rest-mcp --http

Endpoints:

POST /mcp — MCP requests
GET /mcp — SSE event stream (per session)
DELETE /mcp — session termination
GET /health — { status: "ok", version, tools, uptime, memory_mb }

Includes session management (mcp-session-id header), CORS, graceful shutdown.

Environment Variables

Variable	Required	Description
`ONEC_BASE_URL`	yes	Base URL of the 1C HTTP server (e.g. `http://localhost:8080/base`).
`ONEC_LOGIN`	yes	Login for HTTP Basic auth.
`ONEC_PASSWORD`	yes	Password for HTTP Basic auth.
`ONEC_SERVICES`	no	Comma-separated module list (default: `all`).
`HTTP_PORT`	no	If set, server runs in HTTP mode on this port.

Backward-compat: 1C_BASE_URL, 1C_LOGIN, 1C_PASSWORD are also accepted as fallback.

Module filtering (`ONEC_SERVICES`)

Limit registered tools to save LLM context. Modules: catalogs, documents, registers, accounting, constants, shortcuts, reports, odata, batch, changes (plus always-on meta).

bash

ONEC_SERVICES=catalogs,documents npx @theyahia/1c-rest-mcp

The discovery module meta (list_entities, get_document_by_number, get_metadata, describe_entity) is always registered — without it an agent cannot discover the database structure.

Safety: set MCP_DISABLE_SANITIZE=true only if you trust the data source — by default tool output is scanned for prompt-injection patterns. The HTTP client refuses absolute URLs whose origin differs from ONEC_BASE_URL. Ref_Key arguments are validated as GUIDs and string values in get_document_by_number are OData-escaped; the raw $filter/$select/$orderby passthroughs are intentional, so scope what the server can read or write via the 1C user's role, not via these arguments.

Authentication

1C:Enterprise REST API uses HTTP Basic auth. Get credentials from your 1C administrator:

Enable HTTP services and OData publication in the 1C Designer.
Create a 1C user with the role required to read/write the entities you need.
Use that user's login/password as ONEC_LOGIN / ONEC_PASSWORD.
The ONEC_BASE_URL is the URL of the published infobase (the same URL you use for the 1C web client, without /odata/... suffix).

The OData endpoint will be ${ONEC_BASE_URL}/odata/standard.odata/.

Demo Prompts

Try these natural-language prompts in your MCP client:

"List all document types in the 1C database that contain 'Реализация' in the name."

"Find invoice ТД-00123 dated 2026-03-01 — show its lines and total amount."

"Get the last 50 sales documents from the past week, ordered by date descending."

"Read the 'Цены номенклатуры' information register for product UUID abc-123."

"Create a new RealizationOfGoodsAndServices document for counterparty 'ООО Ромашка' with two product lines."

"Run an OData query: Catalog_Номенклатура where Description contains 'кофе', expand Производитель, top 20."

"Get the balance report from /hs/reports/balance?date=2026-04-01 and summarize it."

Development

bash

npm install
npm run build
npm test
npm run dev   # tsx watch mode

Project layout:

code

.
├── src/
│   ├── index.ts            — entry point (runServer; version + docstring)
│   ├── server.ts           — server factory, module config, tool registration
│   ├── client.ts           — functional API + buildKeyedPath + escapeODataString + GUID guard
│   ├── validation.ts       — shared zod field schemas (refKeySchema, odataDate, odataDateTime)
│   ├── types.ts            — OData TypeScript types
│   ├── lib/
│   │   └── errors.ts       — parse Russian 1C errors → category + recovery hint
│   └── tools/
│       ├── catalogs.ts     ├── documents.ts    ├── registers.ts
│       ├── accounting.ts   ├── constants.ts    ├── shortcuts.ts
│       ├── metadata.ts     — discovery (list_entities, get_document_by_number, get_metadata, describe_entity)
│       ├── batch.ts        ├── change-tracking.ts
│       ├── odata-query.ts  └── reports.ts
└── tests/
    ├── client.test.ts      ├── server.test.ts        ├── tools.test.ts
    ├── batch.test.ts       ├── change-tracking.test.ts └── error-parsing.test.ts

License

MIT — see LICENSE.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "1c-rest-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@theyahia/1c-rest-mcp@1.2.1"
      ]
    }
  }
}

Topics

@theyahia/1c-rest-mcp

Migrating from v1.x

Tools (32)

Discovery — meta (always enabled)

Catalogs — catalogs

Documents — documents

Registers — registers

Accounting — accounting

Constants — constants

Shortcuts — shortcuts

Reports — reports

Generic OData — odata

Batch — batch

Change tracking — changes

Prompts

Quick Start

Claude Desktop

Cursor / Windsurf

VS Code (Copilot)

Streamable HTTP transport

Environment Variables

Module filtering (ONEC_SERVICES)

Authentication

Demo Prompts

Development

License

Install

Discovery — `meta` (always enabled)

Catalogs — `catalogs`

Documents — `documents`

Registers — `registers`

Accounting — `accounting`

Constants — `constants`

Shortcuts — `shortcuts`

Reports — `reports`

Generic OData — `odata`

Batch — `batch`

Change tracking — `changes`

Module filtering (`ONEC_SERVICES`)