1C AI MCP - MCP server for 1С:Напарник

MCP server (Model Context Protocol) for integrating IDEs with the 1С:Напарник API. Built on FastMCP (Python), packaged in Docker. Works with Cursor, Claude Code, and any MCP-compatible clients.

12 tools: code analysis (check, review, refactoring) and documentation search (ITS, platform, configurations).

Based on the idea of comol/1c-code-checker with API format fixes (422 errors) borrowed from SteelMorgan/spring-mcp-1c-copilot.

Prerequisites

• Docker (or Docker Desktop)

• 1С:Напарник token - get it at code.1c.ai (ITS subscription required)

Related MCP server: 1C_MCP_SERVER_OWN

Quick Start

Option A: Ready-made image from Docker Hub (recommended)

docker run -d --name 1c-ai-mcp -p 8007:8007 \
  -e ONEC_AI_TOKEN="ваш-токен" \
  desko77/1c-ai-mcp:latest

Or via Docker Compose - create a docker-compose.yml file:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    container_name: 1c-ai-mcp
    ports:
      - "8007:8007"
    environment:
      ONEC_AI_TOKEN: "${ONEC_AI_TOKEN}"
    restart: always

# Создать .env с токеном (не попадает в git)
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Запустить
docker compose up -d

Option B: Build from source

git clone https://github.com/Desko77/1c-ai-mcp.git
cd 1c-ai-mcp

# Создать .env с токеном
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Собрать и запустить
docker compose up -d --build

Checking functionality

# Должен вернуть HTTP 200
curl http://localhost:8007/mcp

Connecting to IDE

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Other MCP clients

Endpoint: http://localhost:8007/mcp Transport: Streamable HTTP (default) or SSE (USESSE=true).

Tools

Code Analysis

check_1c_code

Checks 1C code: syntax, logic, performance. In direct mode, syntax is checked via the upstream syntax-checker.

ask_1c_ai

Arbitrary question to 1С:Напарник. Preserves dialog context between calls.

review_1c_code

Code review: style, ITS standards, naming, structure, readability. Does not check syntax.

rewrite_1c_code

AI suggests its improved version of the code with an explanation of changes.

modify_1c_code

Modifies code according to an explicit instruction. If code is not specified, generates new one.

explain_1c_syntax

Explanation of a specific 1C syntax element.

Documentation and Help

its_help

Search the ITS knowledge base (standards, methods, articles). Returns document IDs for fetch_its.

fetch_its

Read an ITS document by ID. Used after its_help.

search_1c_documentation

Search the 1C:Enterprise platform documentation for a specific version.

onec_help

Search the platform documentation (latest version). Like search_1c_documentation, but without specifying a version.

diff_1c_documentation_versions

Compare platform documentation between two versions.

config_help

Search documentation for applied configurations (ERP, Accounting, ZUP, UT, etc.).

Configuration

All parameters are passed via environment variables.

* Either ONEC_AI_TOKEN or ONEC_AI_TOKEN_FILE is required.

Docker Secrets

For production environments, the token can be passed via a file:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    environment:
      ONEC_AI_TOKEN_FILE: /run/secrets/onec_token
    secrets:
      - onec_token

secrets:
  onec_token:
    file: ./onec_token.txt

Direct Mode

With MCP_TOOL_CALL_MODE=direct, documentation tools and check_1c_code (syntax) call 1С:Напарник upstream tools directly by name, instead of text prompts. This gives more accurate results.

Upstream tools:

• mcp__knowledge-hub__Search_ITS - for its_help

• mcp__knowledge-hub__Fetch_ITS - for fetch_its

• mcp__knowledge-hub__Search_Documentation - for search_1c_documentation, onec_help

• mcp__knowledge-hub__Diff_Documentation_Versions - for diff_1c_documentation_versions

• mcp__syntax-checker__validate - for check_1c_code (syntax)

On direct call failure, automatic fallback to prompt mode. Default is standard for backward compatibility.

Architecture

MCP-клиент (Cursor / Claude Code)
  -> FastMCP HTTP endpoint (:8007/mcp)
    -> mcp_server.py (обработчики инструментов)
      -> OneCApiClient (HTTP-клиент)
        -> code.1c.ai API (SSE-стриминг)
          -> парсинг ответа -> возврат клиенту

Two operation modes

• Standard mode (default): tools form text prompts and send them to the API. Documentation tools use a tool chain - the model itself decides which server tool to call.

• Direct mode (MCP_TOOL_CALL_MODE=direct): tools explicitly request a specific upstream tool by name, match the response, and confirm the call. On failure - automatic fallback to standard mode.

SSE parser

Supports three API response formats:

Additionally:

• Automatic removal of <thinking>/ thinking blocks from responses

• Unicode normalization and cleanup of control characters

• Fallback on receiving tool_calls - repeat request with skill_name="raw"

• Truncation of input data by ONEC_AI_INPUT_MAX_LENGTH

Development

Local run without Docker

pip install -r requirements.txt
export ONEC_AI_TOKEN="ваш-токен"
python main.py

Project structure

main.py                       # Точка входа
src/
  mcp_server.py                # MCP-инструменты (@mcp.tool)
  onec_api_client.py           # HTTP-клиент к API 1С:Напарник
Dockerfile                     # Dockerfile
docker-compose.yml             # Compose для сборки из исходников
tests/                         # Тестовые скрипты
.github/workflows/
  docker-publish.yml           # CI: сборка и публикация в Docker Hub

Acknowledgements

• comol/1c-code-checker - original idea (repository closed)

• SteelMorgan/spring-mcp-1c-copilot - correct API algorithms

• FastMCP - MCP server framework

License

MIT - see LICENSE