1c-mcp
An MCP client for 1C 8.3: metadata, queries, reading documents, and diagnosing why a document will not post inside a transaction that always rolls back
Medium risk
We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
Why this level
- The object_update and document_post write tools, when enabled, change real objects and post documents
- The base user's credentials are stored in the MCP client's environment variables
Install
Manual install
npm install
cp .env.example .env
npm run buildInstalls the client; .env is filled with ONEC_URL, ONEC_USER, ONEC_PASSWORD after implementing the HTTP service in the 1C extension.
This is third-party code. Review the repository files before installing.
What it does
The server is a thin TypeScript client that talks to an mcp HTTP service in your 1C configuration extension. The tools cover reading object metadata, 1C query-language queries, reading objects by reference, listing documents, register movements, and, as the headline feature, posting diagnosis via document_diagnose: the extension checks fill validity, tries to post the document inside a transaction that always rolls back, and returns the error text, the failing attribute, the document data, its metadata and the movements it would have made. The write tools object_update and document_post register only with an explicit ONEC_ALLOW_WRITE=1; by default the server is read-only. The HTTP service on the 1C side has to be implemented yourself against a fixed contract; there is no bundled extension in the repo.
Who it is for. For 1C developers and analysts who want an agent to work out on its own why a document will not post, instead of manually digging through the error in the Configurator.
Good fit when
- You need to find out why a specific document will not post, with the exact error text and failing field
- You want an agent to see base metadata and data, but without a default risk of changing anything
- You are ready to implement the extension's HTTP service against the project's contract
Not a fit when
- You are not ready to write your own extension with an HTTP service: the project ships no ready-made extension
- You need to write to the database without explicitly enabling ONEC_ALLOW_WRITE=1
Example request
Diagnose why document Реализация 0001 dated 01.01.2026 will not post and explain the reasonLimitations
There is no ready-made 1C extension in the repo: the mcp HTTP service has to be implemented yourself in BSL against the documented contract, a separate piece of work. It requires publishing the base on a web server with HTTP services enabled and a dedicated Basic Auth user. The README itself lists a bundled reference extension as a good first contribution, meaning it does not exist yet.
How to disable. Remove the 1c entry from the MCP client config and disable the mcp HTTP service in the base extension.
MCP
- Transport
- stdio
- Authentication
- API key
| Environment variables | |
|---|---|
| ONEC_URL required | The root of the extension's HTTP service, e.g. http://host/base/hs/mcp. |
| ONEC_USER required | The 1C user for Basic Auth. |
| ONEC_PASSWORD required, secret | The 1C user's password. |
| ONEC_ALLOW_WRITE | 1 registers the object_update and document_post write tools; any other value keeps the server read-only. |
Security check
- The object_update and document_post write tools, when enabled, change real objects and post documents
- The base user's credentials are stored in the MCP client's environment variables
README in short
The README explains the motivation: most 1C tools give either metadata or data, while the question 'why won't this document post' needs both plus running the posting logic. It details the document_diagnose mechanism with a BSL code example inside a rolled-back transaction, a table of 11 tools, the full HTTP method contract with request and response shapes, an extension setup checklist, and a security section: writes only behind an explicit flag, credentials only from the environment. The contributor ideas list separately mentions a bundled reference extension. MIT license.
FAQ
Does diagnosis change the database?
No, document_diagnose always rolls back the transaction, so it has zero side effects on the database.
How do I enable writes?
Set the ONEC_ALLOW_WRITE=1 environment variable, which registers the object_update and document_post tools.
Related
A skills library that gives coding agents a development process: brainstorming, planning, TDD, subagents and code review
Skills for real engineers by Matt Pocock
Skills For Real Engineers
Small composable skills for engineering with agents: plan grilling, TDD, bug diagnosis, code review and architecture
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Reference MCP servers
Model Context Protocol servers
Official reference MCP servers: Filesystem, Fetch, Git, Memory, Sequential Thinking, Time and Everything