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

Catalogs — catalogs

Documents — documents

Registers — registers

Accounting — accounting

Constants — constants

Shortcuts — shortcuts

Reports — reports

Generic OData — odata

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.

Change tracking — changes

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

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.

Related MCP server: INFATON MCP35

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

Quick Start

Claude Desktop

Add to claude_desktop_config.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:

{
  "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:

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

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

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:

1. Enable HTTP services and OData publication in the 1C Designer.

2. Create a 1C user with the role required to read/write the entities you need.

3. Use that user's login/password as ONEC_LOGIN / ONEC_PASSWORD.

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

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

Project layout:

.
├── 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.