1C Odata MCP

MCP-servidor para 1С:Предприятие a través de OData: datos de 1С en lenguaje natural desde Claude. Lectura por defecto, escritura por bandera. Funciona con cualquier 1С que tenga OData habilitado — nube (Scloud/1cFresh), servidor con SQL o base de archivos local.

GitHub
19

Documentación

1c-odata-mcp — servidor MCP universal para 1C:Enterprise a través de OData

npm CI smithery license node

Диалог с Claude: на вопрос «кто из покупателей должен больше всего» приходит список должников и итог из 1С

🇬🇧 En resumen: un servidor MCP que conecta 1C:Enterprise con cualquier cliente MCP (Claude, Cursor, VS Code, modelos locales…) a través de la interfaz estándar OData. Pregunte a su base de datos contable en lenguaje natural (deudores, ventas, impuestos, flujo de caja) y obtenga la respuesta; escritura opcional, controlada por vista previa. Solo lectura por defecto. Ejecute con npx -y 1c-odata-mcp. Funciona con cualquier 1C donde OData esté publicado: nube, SQL o base de archivos local.

Servidor MCP (Model Context Protocol) para 1C:Enterprise a través de la interfaz estándar OData. Permite trabajar con datos de 1C en lenguaje natural desde cualquier cliente MCP: Claude, Cursor, VS Code, JetBrains, modelos locales (Ollama, LM Studio): preguntar sobre contrapartes, documentos, saldos, cuentas por cobrar, ventas y movimiento de dinero; y, si se habilita explícitamente, también crear/modificar directorios y documentos, contabilizar y registrar pagos.

Si buscaba cómo conectar 1C a una red neuronal / IA, un conector 1C OData listo para usar o una integración de 1C con Claude sin programación del lado de 1C — esto es lo que necesita.

  • 🔌 Cualquier cliente MCP: Claude Desktop y Claude Code, Cursor, VS Code (Continue/Cline), JetBrains — y modelos locales (Ollama, LM Studio)
  • 🔐 Los datos permanecen en su poder — el servidor es un proceso local, solo accede a su base; con un modelo local los datos ni siquiera salen de la red
  • 🏢 Varias bases de información y organizaciones (personas jurídicas) simultáneamente
  • 🔒 Solo lectura por defecto; escritura — mediante doble seguro y vista previa
  • 🚀 Inicio con un solo comando: npx -y 1c-odata-mcp
  • ⚙️ No se instala nada del lado de 1C — basta con tener OData publicado (sin conexión COM, sin acceso a SQL)

📘 Instalación, publicación de OData y conexión a Claude — paso a paso en docs/CONNECTING.md. Aquí — sobre el proyecto en sí, sus capacidades y limitaciones.

Adecuado para cualquier variante de su 1C

El conector se comunica con 1C solo a través de OData. Si está habilitado, todo funciona igual, sin importar cómo esté desplegada su base:

Su 1CQué se necesita para que funcioneComplejidad
Nube / hosting (Scloud, 1cFresh, alquiler de 1C)OData lo habilita el proveedor — con una casilla en el panel o mediante solicitud🟢 baja
Servidor con SQL (PostgreSQL / MS SQL)publicar la base en Apache/IIS + habilitar OData🟡 media
Base de archivos local (.1CD)lo mismo + dar al servidor web permisos sobre la carpeta de la base🟡 media
Sin servidor web / sin acceso al configuradorOData no está disponible → se necesita otro transporte🔴

El tipo de almacenamiento (archivo o SQL) por sí mismo no cambia la complejidad — lo importante es si la publicación web de OData está levantada. Sin OData habilitado el conector no puede funcionar (no usa COM ni accede directamente a SQL).

➡️ Instrucciones paso a paso para cada variante — en docs/ODATA-SETUP.md. Dirección de la base, credenciales y conexión a Claude — en docs/CONNECTING.md.

Para qué sirve

El OData crudo de 1C son cientos de EntitySet técnicos con nombres cirílicos (Catalog_Контрагенты, Document_РеализацияТоваровУслуг, AccumulationRegister_ТоварыНаСкладах) y claves GUID. Trabajar con esto desde un chat es imposible, y escribir código propio para cada informe lleva mucho tiempo.

El servidor oculta toda la parte técnica detrás de herramientas comprensibles. Usted pregunta en lenguaje normal — la IA elige la herramienta adecuada, accede al OData de su base y devuelve la respuesta lista. Para un directivo — una visión rápida del negocio; para un contador — la rutina de creación de documentos bajo control.

Capacidades

Analítica y lectura (por defecto):

  • «Muéstrame las cuentas por cobrar» → saldo de la cuenta 62 por contraparte
  • «Historial de la contraparte Romashka» → todos los documentos y liquidaciones mutuas
  • «Saldos en el almacén» → cantidad y suma por artículo
  • «Ventas de mayo», «movimiento de dinero del trimestre» → movimientos del período
  • búsqueda de contrapartes y documentos, fichas de objetos, mapa de la base

Acciones (con escritura habilitada, siempre con vista previa y confirmación):

  • «Crea la contraparte OOO Romashka, INN …, teléfono, email, cuenta bancaria, director»
  • «Emite una factura al comprador por 3 uds a 1000» → documento borrador
  • «Crea un ingreso del proveedor y una venta al comprador», «contabiliza el documento» → los asientos los genera la propia 1C
  • «Registra una devolución del comprador», «traslado entre almacenes», «entrada / baja / inventario»
  • «Registra el pago», «cargo de la cuenta bancaria», «orden de caja de entrada / salida»
  • «Emite una factura de venta», «acta de prestación de servicios»
  • «Haz el acta de julio como la de junio, cambia el período y la cantidad» → copia del documento anterior con todos los requisitos (contenido de líneas, cuentas contables, cuenta bancaria) — así se emiten documentos mensuales
  • modificación de requisitos, líneas de documentos; contabilización y marcado para eliminación

Se puede leer un documento de cualquier tipo (no solo de la lista anterior) — «muestra las devoluciones de mayo», «encuentra los traslados», etc.

La lista completa — en la sección Herramientas.

Ejemplo de diálogo

A continuación — Claude Desktop, pero el diálogo se ve igual en cualquier cliente MCP.

Вы:     Кто из покупателей должен больше всего и на сколько?
Claude: (вызывает read.analytics.get_debtors) Топ дебиторов на сегодня:
        1. ООО «Ромашка» — 1 240 500 ₽
        2. ИП Иванов     —   318 000 ₽
        3. ООО «Берёзка» —    94 050 ₽
        Всего по счёту 62: 1 800 000 ₽.

Вы:     Заведи нового покупателя ООО «Восход», ИНН 7701234567, и выстави счёт на 10 шт по 2500.
Claude: (dry-run) Будут созданы:
        • Контрагент «ООО Восход» (ИНН 7701234567)
        • Счёт покупателю на 25 000 ₽ (10 × 2500)
        Подтвердить создание?
Вы:     Да
Claude: Готово: контрагент 00-000123, счёт № … (черновик, непроведён).

Inicio rápido

¿Es la primera vez que oye hablar de MCP? Es un protocolo abierto (Model Context Protocol) mediante el cual un asistente de IA se conecta a herramientas externas. Aquí la herramienta es su 1C: el asistente llama a las funciones necesarias y devuelve la respuesta. No hay que programar nada — solo tres pasos a continuación.

  1. Publique OData en 1C y añada los objetos necesarios a la «Composición» (detalles — docs/CONNECTING.md; si OData aún no está habilitado — docs/ODATA-SETUP.md).

  2. Configure el servidor en Claude Desktop (claude_desktop_config.json), sustituyendo la dirección y las credenciales:

    {
  "mcpServers": {
    "1c-odata": {
      "command": "npx",
      "args": ["-y", "1c-odata-mcp"],
      "env": {
        "ODATA_BASE_URL": "https://<сервер>/<база>/odata/standard.odata/",
        "ODATA_USERNAME": "...",
        "ODATA_PASSWORD": "..."
      }
    }
  }
}

  3. Reinicie Claude Desktop (por completo) y pregunte: «comprueba la conexión con 1C».

Configuración completa (dirección OData según plataforma, autorización, ejecución desde el código fuente, Claude Code, diagnóstico de errores) — en docs/CONNECTING.md.

Herramientas

56 herramientas (21 de lectura/análisis + 35 de escritura). Todas tienen el parámetro opcional database (qué base de 1C — ver read.system.list_databases); las analíticas también tienen organization (filtro por persona jurídica — ver read.system.list_organizations).

Lectura y análisis:

HerramientaQué hace
read.system.list_databases / read.system.list_organizationsLista de bases / organizaciones (para los parámetros database / organization)
read.organization.get_organization_cardFicha de la organización: INN/KPP/OGRN, OKVED, órgano fiscal, direcciones, cuenta bancaria, director y contador jefe
read.schema.list_entities / read.schema.describe_entityMapa de objetos de la base y campos de un objeto concreto (de $metadata)
read.counterparty.find_counterparty / read.counterparty.get_counterpartyBúsqueda de contraparte (por nombre/INN) y su ficha
read.document.search_documents / read.document.get_documentBúsqueda de documentos y documento con parte tabular
read.analytics.get_debtors / read.analytics.get_inventoryCuentas por cobrar (cta. 62) / saldos de mercancías (cta. 41/10/43), se puede a fecha pasada (asOf)
read.analytics.get_sales / read.analytics.get_cashflowVentas del período / movimiento de dinero (banco + caja)
read.analytics.get_sales_breakdown / read.analytics.get_purchases_breakdownVentas/compras desglosadas por contraparte, mes, contrato, categoría (IP/Persona Jurídica/…)
read.analytics.get_payments_breakdownIngresos/gastos por tipo de operación, mes, contraparte, artículo de flujo de caja — «cuánto se pagó a los IP durante el año», «intereses del depósito»
read.analytics.get_taxes_paidImpuestos y contribuciones pagados en el período, desglosados por tipo de impuesto
read.analytics.get_deal_historyCronología de movimientos de una operación (código en la referencia del pago) o contrato
read.counterparty.get_customer_history / read.counterparty.get_supplier_historyHistorial de liquidaciones mutuas con el comprador / proveedor
read.system.health_checkVerificación de conexión y autorización

Escritura (✍️ requiere habilitación, funciona mediante dry-run → confirm=true):

HerramientaQué hace
write.counterparty.create_counterpartyContraparte (+ teléfono/email/dirección/OGRN)
write.counterparty.create_bank_account / write.counterparty.create_contact_personCuenta bancaria (banco por BIK) / persona de contacto (director)
write.catalog.create_nomenclatureArtículo (carpeta, código de artículo, indicador de servicio)
write.catalog.create_contractContrato (tipo, número, moneda, tipo de precios, responsable de la contraparte)
write.sales.create_invoice / write.purchase.create_supplier_invoiceFactura al comprador / factura de pago al proveedor (sin contabilizar)
write.purchase.create_purchase / write.sales.create_shipmentIngreso del proveedor / venta al comprador
write.warehouse.create_return_from_customer / write.warehouse.create_return_to_supplierDevolución de mercancías del comprador / al proveedor
write.warehouse.create_transferTraslado de mercancías entre almacenes
write.warehouse.create_surplus / write.warehouse.create_writeoffEntrada / baja de mercancías
write.warehouse.create_inventoryInventario de mercancías en el almacén
write.sales.create_actVenta de servicios (acta)
write.sales.create_services_actActa de prestación de servicios (ingresos/gastos por grupo de artículos)
write.money.create_payment / write.money.create_payout_orderPago del comprador (ingreso en c/c) / orden de pago
write.money.create_bank_writeoffCargo de la cuenta bancaria (pago saliente, tipo de operación obligatorio)
write.money.create_cash_receipt / write.money.create_cash_paymentOrden de caja de entrada / salida (PCO / RCO)
write.sales.create_issued_invoice / write.purchase.create_received_invoiceFactura emitida / recibida (sobre la base de la venta / ingreso)
write.entity.create_folder / write.entity.move_to_folderCarpeta (grupo) del directorio / movimiento a carpeta
write.counterparty.update_counterparty / write.catalog.update_nomenclature / write.entity.update_entityModificación de requisitos (PATCH)
write.document.copy_documentDocumento según modelo de uno existente — con todos los requisitos
write.document.update_document_lines / write.document.add_document_line / write.document.remove_document_lineEdición de líneas de documento
write.document.post_documentContabilizar / cancelar contabilización (1C genera los asientos)
write.entity.mark_for_deletionMarcar para eliminación / quitar marca (eliminación suave)

Todas las herramientas están probadas en una base real de 1C:Contabilidad Empresarial 3.0.

Las líneas de documentos de venta y compra aceptan:

  • content — requisito «Contenido». Es este texto el que se imprime en la factura y en el UPD («Servicios según anexo n.º 4 del 01.10.2025 al contrato n.º 87 … por julio de 2026»). La propia 1C no lo rellena, así que para servicios indíquelo explícitamente.

  • incomeAccount / expenseAccount — cuentas de ingresos y gastos por código como en 1C (90.01.2, 90.02.2) o mediante Ref_Key. También se pueden definir para todo el documento. Prioridad: línea → documento → registro «Cuentas contables de artículos» → 90.01.1 / 90.02.1. Las cuentas se aplican a documentos de venta; la factura de pago y el ingreso no las usan.

  • orgBankAccount (factura al comprador, venta, acta) — cuenta bancaria de la organización, que se imprime como datos para el pago: nombre, número de cuenta o Ref_Key. Si no se indica, se toma la cuenta principal de la organización.

write.document.add_document_line y remove_document_line reconstruyen la parte tabular, conservando los requisitos de las líneas anteriores — contenido, cuentas contables, grupo de artículos. update_document_lines sustituye las líneas por completo, por lo que allí se definen de nuevo. Las líneas se escriben en la parte tabular que esté rellena en el documento: en el acta de servicios es «Servicios», en el documento de mercancías — «Mercancías».

Documentos mensuales recurrentes es más fácil emitirlos mediante write.document.copy_document: toma el documento anterior como modelo y traslada todos los requisitos, incluidos los que no están en los esquemas de create_* — cuenta bancaria, responsable, dirección de entrega, condiciones adicionales de la factura. Se cambian con la fecha (date), los requisitos de la cabecera (fields) y las correcciones de líneas por número (lines).

Seguridad

Por defecto el servidor funciona solo en lectura. La escritura se habilita de forma consciente, mediante dos seguros independientes:

  1. Interruptor global READ_ONLY=false.
  2. Indicador por base ODATA_DB_<ИМЯ>_WRITABLE=true — las bases sin él permanecen de solo lectura incluso con el global desactivado. Así se puede abrir la escritura en una base (p. ej., IP) y proteger otras (p. ej., OOO).

Además, al escribir:

  • dry-run por defecto — la herramienta primero muestra lo que creará y solo escribe cuando confirm=true;
  • borrado suave — write.entity.mark_for_deletion coloca una marca (como en 1C); no existe borrado físico DELETE;
  • en el lado de 1C, en «Composición de OData» solo se habilitan los objetos necesarios, y el usuario de 1C debe tener permisos de escritura.

Privacidad de datos. El servidor es un proceso local en su máquina: solo accede a su base 1C (mediante autenticación Basic) y entrega los datos a su cliente MCP. No hay servidores externos del proyecto en la cadena. Si usa un modelo local (Ollama, LM Studio), los datos de 1C no salen de su red. Los secretos provienen únicamente de .env (o del bloque env de la configuración); la contraseña y el encabezado de autorización no aparecen en los registros.

Cómo habilitar la escritura exactamente — docs/CONNECTING.md → Habilitar escritura.

Varias bases y varias organizaciones

Son casos diferentes:

  • Varias bases separadas (diferentes direcciones OData) — un solo servidor atiende todas; el nombre de la base se pasa como parámetro database. Configuración en .env — ver docs/CONNECTING.md. Ejemplo de consulta: «compara los ingresos de buh y torg de mayo».
  • Varias organizaciones (personas jurídicas) en una misma base — no se necesita una conexión separada, funciona el filtro organization. Ejemplo: «saldos por organización Romashka».

Limitaciones

Conviene saberlo de antemano:

  • Se necesita OData publicado. El servidor solo funciona a través de la interfaz estándar OData de 1C. No usa ni requiere acceso directo a SQL, conexiones COM ni archivos del servidor 1C.
  • El objeto debe estar en «Composición de OData». Si el objeto no está publicado, la herramienta devolverá una sugerencia amable con el nombre del objeto y la ruta para agregarlo. Publique según sea necesario.
  • Configuración objetivo: Contabilidad Empresarial 3.0. Los nombres de objetos se autodetectan desde $metadata, pero el análisis (cuentas por cobrar/saldos) y las cuentas contables de documentos están diseñados para el plan de cuentas de BP 3.0. En UT/ERP y configuraciones personalizadas, la lectura de directorios/documentos funciona, pero el análisis contable puede requerir ajustes.
  • Los documentos se crean sin contabilizar. Las contabilizaciones las genera la propia 1C al contabilizar (write.document.post_document o manualmente) — el servidor no «dibuja» contabilizaciones directamente.
  • Las operaciones reglamentarias no se crean. El cierre de mes, la amortización, el cálculo del costo/IVA los genera el procesamiento «Cierre de mes» con sus propios algoritmos — no se pueden ejecutar a través de OData. Leer (read.document.search_documents/read.document.get_document) sí es posible.
  • Pago (write.money.create_payment). El documento se crea y se contabiliza, pero las contabilizaciones contables Dt 51 Kt 62 solo se generan si la cuenta bancaria de la organización tiene configurada la cuenta contable (51) — es una configuración en 1C.
  • OGRN y otros atributos adicionales. Solo se escriben si en la base existe el «atributo adicional» correspondiente (Administración → Atributos adicionales). De lo contrario, la herramienta informa honestamente que no hay dónde escribirlos.
  • La dirección se escribe como texto de representación (no una dirección FIAS estructurada).
  • Paginación y límites. Para no descargar miles de filas, se aplica un tamaño de página y un máximo de protección (ODATA_PAGE_SIZE / ODATA_MAX_ROWS); las selecciones grandes se truncan con una marca.

Cómo está estructurado

Proceso local en Node.js, se comunica con el cliente mediante el protocolo MCP a través de stdio, y con 1C por HTTP a OData (autenticación Basic). Stack: Node.js 20+, TypeScript (estricto), @modelcontextprotocol/sdk oficial, fetch nativo, zod (validación), pino (registros en stderr), fast-xml-parser (análisis de $metadata).

El mapa de objetos se construye automáticamente desde $metadata de la base y se almacena en caché; las consultas se ensamblan con un constructor tipado. Varias bases: cada una tiene su propio cliente y su propia caché de metadatos.

src/
  index.ts            точка входа
  context.ts          реестр баз: Connection (клиент + кеш $metadata) + ServerContext
  mcp/server.ts       инициализация MCP SDK, регистрация инструментов, stdio
  odata/              клиент, билдер запросов, пагинация, разбор $metadata, аналитика,
                      справочные резолверы, обработка ошибок, проверка публикации
  tools/              инструменты: meta, counterparties, documents, registers, cashflow,
                      sales, organization, write
  config/             конфигурация (.env, мультибаза) и маппинг имён/счетов
  types/              типы OData и доменные типы

Notas técnicas

  • + vs %20 en OData 1C. 1C no decodifica + como espacio dentro de $filter (responde 400), por lo que la cadena de consulta se construye mediante encodeURIComponent (espacio → %20), no URLSearchParams.
  • Cuentas contables de documentos no se insertan automáticamente a través de OData (eso lo hace el formulario de 1C al seleccionar la nomenclatura) — el servidor las toma del registro «Cuentas contables de nomenclatura», con respaldo a los códigos estándar del plan de cuentas.
  • Registros y stderr. stdout está ocupado por JSON-RPC, por lo que los registros van a stderr — pero solo en la terminal. Bajo un cliente MCP (cuando stdin es pipe), los registros se escriben en el archivo <tmpdir>/1c-odata-mcp/server.log para no romper clientes que interpretan cualquier salida en stderr como error fatal. Para devolver los registros a stderr: MCP_LOG_STDERR=1.
  • Respuestas tipadas. Los 56 instrumentos declaran outputSchema — los clientes que admiten structuredContent (no solo JSON de texto) pueden tipar la respuesta sin analizar el texto.
  • Nombres de instrumentos. dot-notation de tres segmentos: <read|write>.<категория>.<имя> (p. ej., read.analytics.get_debtors, write.sales.create_shipment) — agrupa los instrumentos por categoría y se ve de inmediato si es lectura o escritura.

Preguntas frecuentes (FAQ)

El cliente MCP «se cuelga» / la consulta falla por tiempo de espera. Si incluso las llamadas pequeñas se cuelgan (read.system.health_check, read.system.list_databases), casi siempre es un proceso MCP atascado (en Claude Desktop se soluciona reiniciando completamente la aplicación, Cmd+Q y volver a abrir), no la base. Un read.system.health_check sano responde en un segundo.

Indico otra base y aparece «no disponible» / solo responde una. El parámetro database es el nombre de read.system.list_databases (campo name, p. ej., ooo), no el nombre «humano» (etiqueta, p. ej., «OOO Romashka»). Diríjase por nombre.

Respuesta vacía / «0 objetos». No está configurada la Composición de OData — agregue los objetos necesarios en 1C (ver docs/ODATA-SETUP.md y docs/CONNECTING.md).

Funciona lento. Es la latencia de su 1C / hosting, no de Claude: las selecciones anuales en bases «ruidosas» pueden tardar 10–30 segundos. Consulte con un período más acotado (trimestre/mes) — la respuesta llega en segundos.

¿Se necesita acceso SQL a la base o COM? No. El servidor usa solo OData — no se instala nada dentro de 1C, no accede directamente a SQL.

¿Es seguro dejar que la IA acceda a la base de producción? Por defecto — solo lectura. La escritura se habilita con dos indicadores independientes y funciona mediante vista previa (dry-run) con confirmación. No hay borrado físico (solo marca). Ver Seguridad.

¿Qué 1C sirve? Cualquiera con OData habilitado — nube (Scloud/1cFresh), servidor con SQL o base de archivos local. Pasos para cada caso — docs/ODATA-SETUP.md.

Agradecimientos

  • @Alexsab — trabajo con documentos en 0.4.0: copy_document, «Contenido» en líneas, cuentas explícitas de ingresos/gastos, selección de la cuenta bancaria de la organización, clase separada de errores de entrada. Y, lo más valioso, errores encontrados en una base real que no se detectan con pruebas unitarias: la edición de líneas de acta se perdía fuera de su parte tabular, y la selección de la cuenta bancaria estaba rota en silencio.

¿Encontró un error o falta documentación? — issue y los PR son bienvenidos. Son especialmente valiosos los hallazgos en bases reales: las configuraciones de 1C varían, y lo que funciona en una, en otra responde con error 500.

Licencia

MIT. Proyecto abierto — úselo, haga fork, envíe issues y PR: https://github.com/evilbruce666/1c-odata-mcp.

⭐ Si el conector le resultó útil — ponga una estrella en GitHub y cuente en Discussions qué preguntas le hace a su 1C. Es la mejor motivación para desarrollar el proyecto.