Content
# 1C MCP Toolkit
**System for integrating AI-agents with 1C:Enterprise databases via MCP and REST API**
## 📋 Description
1C MCP Toolkit is a solution for connecting AI-agents (Kiro, Claude, etc.) to 1C:Enterprise databases. It supports two operation modes: **embedded server** (HTTP server runs directly inside the 1C processing, without Python) and **proxy** (Python server with long polling).
**Key benefits:**
- ✅ No need to change 1C configuration
- ✅ No need to publish 1C server
- ✅ Does not use COM-connection
- ✅ Compatible with 1C:Enterprise 8.2.13+ / 8.3.25
- ✅ **Embedded server**: Python not required — HTTP server runs directly in 1C
- ✅ Supports Docker (Proxy mode)
## 🏗️ Architecture
### Option 1: Embedded Server
HTTP server runs directly inside the 1C processing. Python not required.
```
┌─────────────────┐ MCP / REST API ┌──────────────────┐
│ AI Agent │ ◄───────────────► │ 1C (.epf) │
│ (Kiro, Claude) │ /mcp /api/* │ Embedded HTTP server│
└─────────────────┘ └──────────────────┘
│
▼
┌───────────────┐
│ 1C Database │
└───────────────┘
```
### Option 2: Proxy Mode
```
┌─────────────────┐ MCP / REST API ┌─────────────────┐
│ AI Agent │ ◄─────────────────────────► │ │
│ (Kiro, Claude) │ /mcp /api/* │ Python Proxy │
└─────────────────┘ │ Server │
│ │
┌─────────────────┐ HTTP Long Polling │ (FastAPI + │
│ 1C Processing │ ◄─────────────────────────► │ MCP SDK) │
│ (external .epf) │ /1c/poll, /1c/result │ │
└─────────────────┘ └─────────────────┘
│ │
▼ │
┌─────────────────┐ ┌───────┴───────┐
│ 1C Database │ │ Docker │
│ (8.2.13/8.3.25) │ │ Container │
└─────────────────┘ └───────────────┘
```
## 🚀 Quick Start
### Option 0: Embedded Server (without Python, recommended)
1. Open `build/MCP_Toolkit.epf` in 1C:Enterprise
2. Select **Embedded server** mode
3. Click "Run server"
4. Configure AI-agent to `http://<1C-computer-ip>:6003/mcp`
### Option 1: Docker Hub (Proxy mode)
Run proxy server from Docker Hub image:
```bash
docker run -d -p 6003:6003 -e ALLOW_DANGEROUS_WITH_APPROVAL=true --restart unless-stopped --name 1c-mcp-toolkit-proxy roctup/1c-mcp-toolkit-proxy
```
### Option 2: Docker Compose
```bash
# Clone repository
git clone <repository-url>
cd 1c-mcp-toolkit
# Run via Docker Compose
docker-compose up -d
```
### Option 3: Direct Python Launch
```bash
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
# or
source .venv/bin/activate # Linux/Mac
# Install dependencies
pip install -r requirements.txt
# Run server
python -m onec_mcp_toolkit_proxy
```
Server will start at `http://localhost:6003`
## 📦 Installing 1C Processing
1. Download ready-made processing from `build` folder **[MCP_Toolkit.epf](./build/MCP_Toolkit.epf)**
2. Open processing in 1C (File → Open)
3. In processing settings, specify:
- Proxy server URL: `http://localhost:6003`
- (optional) Channel ID for command isolation
4. Click "Connect" button
## ⚙️ Configuring AI-Agent
### Kiro IDE
Add to `.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"onec-mcp-toolkit-proxy": {
"url": "http://localhost:6003/mcp",
"transport": "http",
"type": "streamable-http",
"disabled": false,
"autoApprove": ["execute_query", "get_metadata"]
}
}
}
```
### Claude Desktop
Open configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add configuration:
```json
{
"mcpServers": {
"onec-mcp-toolkit-proxy": {
"url": "http://localhost:6003/mcp",
"transport": "http"
}
}
}
```
Restart application.
## 🛠️ Available MCP Tools
| Tool | Description |
|-----------|----------|
| **execute_query** | Executing queries in 1C query language |
| **execute_code** | Executing arbitrary 1C code |
| **get_metadata** | Getting metadata structure information |
| **get_event_log** | Getting records from registration log |
| **get_object_by_link** | Getting object by navigation link |
| **get_link_of_object** | Generating navigation link to object |
| **find_references_to_object** | Searching for all references to object |
| **get_access_rights** | Getting access rights to metadata objects |
| **get_bsl_syntax_help** | Reference on built-in BSL language: searching for functions, methods, types, and language constructs |
| **submit_for_deanonymization** | Sending final answer for deanonymization (only with enabled anonymization) |
## 🌐 REST API (alternative to MCP)
For AI-agents that do not support MCP protocol or prefer standard HTTP requests, proxy provides REST API with the same functionality.
**Base URL:** `http://localhost:6003/api/`
### Available Endpoints
| Endpoint | Method | Description |
|----------|-------|----------|
| `/api/execute_query` | POST | Executing 1C queries |
| `/api/execute_code` | POST | Executing 1C code |
| `/api/get_metadata` | GET/POST | Getting metadata |
| `/api/get_event_log` | POST | Registration log |
| `/api/get_object_by_link` | POST | Get object by link |
| `/api/get_link_of_object` | POST | Generating link to object |
| `/api/find_references_to_object` | POST | Searching for references to object |
| `/api/get_access_rights` | POST | Getting access rights |
| `/api/get_bsl_syntax_help` | POST | Reference on BSL language |
| `/api/submit_for_deanonymization` | POST | Sending text for deanonymization (only with enabled anonymization) |
### Response Format
Most responses follow a unified structure:
**Success:** `{"success": true, "data": <result>}`
**Error:** `{"success": false, "error": "Error description"}`
**Exception:** `submit_for_deanonymization` returns `{"received": true}` on success (without `data` field).
Detailed usage examples of REST API are available in full documentation.
## 🕵️ Data Anonymization
The tool supports automatic anonymization of personal and confidential data. Real values are replaced with stable tokens (`[ORG-00001]`, `[PER-00001]`, `[INN-00001]`, etc.). Agent can pass tokens back to queries — server automatically restores real values.
**Embedded server mode:**
- Configuration via 1C processing form: metadata fields tree, dictionary from 1C reference books, regular expressions
**Proxy mode:**
- Controlled by environment variables (`ANONYMIZATION_ENABLED=true`)
- Additionally: SpaCy NER, token isolation by channels, smart anonymization of column aliases
Full documentation: **[ANONYMIZATION.md](./ANONYMIZATION.md)**
## 🔒 Security
- Dangerous operations are blocked by a customizable blacklist
- Use `ALLOW_DANGEROUS_WITH_APPROVAL=true` for approval mode
- Recommended to configure `autoApprove` only for safe tools
## 📝 Channel Isolation
When connecting multiple 1C clients to one proxy server, you can isolate command flows using channel IDs.
### Usage with MCP
```json
{
"mcpServers": {
"onec-dev": {
"url": "http://localhost:6003/mcp?channel=dev-environment",
"transport": "http",
"type": "streamable-http"
},
"onec-prod": {
"url": "http://localhost:6003/mcp?channel=prod-environment",
"transport": "http",
"type": "streamable-http"
}
}
}
```
### Usage with REST API
All REST endpoints support channel isolation via `?channel=<id>` query parameter:
```bash
# Development channel
curl -X POST "http://localhost:6003/api/execute_query?channel=dev-environment" \
-H "Content-Type: application/json" \
-d '{"query": "ВЫБРАТЬ 1"}'
# Production channel
curl -X POST "http://localhost:6003/api/execute_query?channel=prod-environment" \
-H "Content-Type: application/json" \
-d '{"query": "ВЫБРАТЬ 1"}'
```
**Important:** Specify the same channel ID in 1C processing settings for corresponding environment.
## 🎓 Skills for AI-Agents
When using **REST API**, it's recommended to use ready-made skills that contain detailed instructions for working with 1C MCP Toolkit.
### Available Skills
📁 **Folder:** `skills/`
| Skill | Description | Recommended for |
|-------|----------|-------------------|
| **calling-1c-rest-api-via-curl** | Complete guide on using REST API via curl: all endpoints, request/response formats, workflow examples, error handling | REST API clients, automation, scripts |
| **composing-1c-queries** | Rules for composing correct 1C queries: syntax, optimization, virtual tables, temporary tables, JOINs | Working with 1C data via execute_query |
### How to Use
Skills contain detailed instructions and reference documentation for AI-agents. Each skill includes:
- Description of capabilities
- Usage examples
- Best practices
- Typical work patterns
For AI-agents using REST API, the `calling-1c-rest-api-via-curl` skill is the primary guide and contains all necessary details for efficient API usage.
## 📚 Documentation
Full documentation is available in **[README_FULL](./README_FULL.md)**
