1C Odata MCP

MCP-servidor para 1С:Enterprise via OData: dados do 1С em linguagem natural a partir do Claude. Leitura por padrão, gravação por flag. Funciona com qualquer 1С que tenha OData habilitado — nuvem (Scloud/1cFresh), servidor com SQL ou banco de arquivos local.

GitHub
19

Documentação

1c-odata-mcp — servidor MCP universal para 1C:Enterprise via OData

npm CI smithery license node

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

🇬🇧 Em resumo: um servidor MCP que conecta o 1C:Enterprise a qualquer cliente MCP (Claude, Cursor, VS Code, modelos locais…) por meio da interface padrão OData. Pergunte ao seu banco contábil em linguagem natural (devedores, vendas, impostos, fluxo de caixa) e receba os números de volta; gravação opcional, protegida por pré-visualização. Somente leitura por padrão. Execute com npx -y 1c-odata-mcp. Funciona com qualquer 1C onde o OData esteja publicado — nuvem, SQL ou base de arquivos local.

Servidor MCP (Model Context Protocol) para 1C:Enterprise via interface padrão OData. Permite trabalhar com dados do 1C em linguagem natural a partir de qualquer cliente MCP — Claude, Cursor, VS Code, JetBrains, modelos locais (Ollama, LM Studio): perguntar sobre contrapartes, documentos, saldos, contas a receber, vendas e fluxo de caixa — e, quando explicitamente habilitado, também criar/alterar diretórios e documentos, lançar, registrar pagamentos.

Se você procurava como conectar o 1C a uma rede neural / IA, um conector 1C OData pronto ou uma integração do 1C com o Claude sem programação no lado do 1C — é isto aqui.

  • 🔌 Qualquer cliente MCP: Claude Desktop e Claude Code, Cursor, VS Code (Continue/Cline), JetBrains — e modelos locais (Ollama, LM Studio)
  • 🔐 Os dados permanecem com você — o servidor é um processo local, acessa apenas o seu banco; com modelo local, os dados nem saem da rede
  • 🏢 Várias bases de informações e organizações (pessoas jurídicas) simultaneamente
  • 🔒 Somente leitura por padrão; gravação — com dupla proteção e pré-visualização
  • 🚀 Início com um único comando: npx -y 1c-odata-mcp
  • ⚙️ Nada é instalado no lado do 1C — basta o OData publicado (sem conexão COM, sem acesso ao SQL)

📘 Instalação, publicação do OData e conexão ao Claude — passo a passo em docs/CONNECTING.md. Aqui — sobre o projeto em si, recursos e limitações.

Serve para qualquer variante do seu 1C

O conector se comunica com o 1C somente via OData. Se ele estiver habilitado — tudo funciona igual, independentemente de como sua base esteja implantada:

Seu 1CO que é necessário para funcionarComplexidade
Nuvem / hospedagem (Scloud, 1cFresh, aluguel de 1C)OData é habilitado pelo provedor — com uma marcação no painel ou por solicitação🟢 baixa
Servidor com SQL (PostgreSQL / MS SQL)publicar a base no Apache/IIS + habilitar OData🟡 média
Base de arquivos local (.1CD)o mesmo + conceder ao servidor web permissões na pasta da base🟡 média
Sem servidor web / sem acesso ao configuradorOData indisponível → é necessário outro transporte🔴

O tipo de armazenamento (arquivo ou SQL) por si só não altera a complexidade — o importante é apenas se a publicação web do OData está ativa. Sem o OData habilitado, o conector não funciona (ele não usa COM nem acessa o SQL diretamente).

➡️ Instruções passo a passo para cada variante — em docs/ODATA-SETUP.md. Endereço da base, credenciais e conexão ao Claude — em docs/CONNECTING.md.

Para que serve

O OData bruto do 1C são centenas de EntitySet técnicos com nomes cirílicos (Catalog_Контрагенты, Document_РеализацияТоваровУслуг, AccumulationRegister_ТоварыНаСкладах) e chaves GUID. Trabalhar com isso pelo chat é impossível, e escrever código próprio para cada relatório é demorado.

O servidor esconde toda a parte técnica por trás de ferramentas compreensíveis. Você pergunta em linguagem comum — a IA escolhe a ferramenta certa, acessa o OData da sua base e retorna a resposta pronta. Para o gestor — um panorama rápido do negócio; para o contador — a rotina de criação de documentos sob controle.

Recursos

Análise e leitura (padrão):

  • «Mostre as contas a receber» → saldo da conta 62 por contraparte
  • «Histórico da contraparte Romashka» → todos os documentos e liquidações mútuas
  • «Saldos no estoque» → quantidade e valor por item
  • «Vendas de maio», «fluxo de caixa do trimestre» → movimentações do período
  • busca de contrapartes e documentos, fichas de objetos, mapa da base

Ações (com gravação habilitada, sempre com pré-visualização e confirmação):

  • «Cadastre a contraparte Romashka Ltda., CNPJ …, telefone, e-mail, conta bancária, diretor»
  • «Emita fatura ao comprador de 3 unidades a 1000» → documento-rascunho
  • «Crie entrada de fornecedor e venda ao comprador», «lance o documento» → lançamentos gerados pelo próprio 1C
  • «Registre devolução do comprador», «transferência entre almoxarifados», «entrada / baixa / inventário»
  • «Registre pagamento», «baixa da conta bancária», «recibo / ordem de pagamento de caixa»
  • «Emita nota fiscal da venda», «termo de prestação de serviços»
  • «Faça o termo de julho igual ao de junho, altere o período e a quantidade» → cópia do documento anterior com todos os atributos (conteúdo das linhas, contas contábeis, conta bancária) — assim se emitem documentos mensais
  • alteração de atributos, linhas de documentos; lançamento e marcação para exclusão

É possível ler documentos de qualquer tipo (não apenas os da lista acima) — «mostre as devoluções de maio», «encontre transferências» etc.

A lista completa — na seção Ferramentas.

Exemplo de diálogo

Abaixo — Claude Desktop, mas o diálogo é igual em qualquer 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, счёт № … (черновик, непроведён).

Início rápido

É a primeira vez que ouve falar de MCP? É um protocolo aberto (Model Context Protocol) pelo qual o assistente de IA se conecta a ferramentas externas. Aqui, a ferramenta é o seu 1C: o assistente chama as funções necessárias e retorna a resposta. Não é preciso programar nada — três passos abaixo.

  1. Publique o OData no 1C e adicione os objetos necessários em «Composição» (detalhes — docs/CONNECTING.md; se o OData ainda não estiver habilitado — docs/ODATA-SETUP.md).

  2. Configure o servidor no Claude Desktop (claude_desktop_config.json), inserindo o endereço e as credenciais:

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

  3. Reinicie o Claude Desktop (completamente) e pergunte: «verifique a conexão com o 1C».

Configuração completa (endereço OData por plataforma, autenticação, execução a partir do código-fonte, Claude Code, diagnóstico de erros) — em docs/CONNECTING.md.

Ferramentas

56 ferramentas (21 leitura/análise + 35 gravação). Todas têm o parâmetro opcional database (qual base 1C — veja read.system.list_databases); as analíticas também têm organization (filtro por pessoa jurídica — veja read.system.list_organizations).

Leitura e análise:

FerramentaO que faz
read.system.list_databases / read.system.list_organizationsLista de bases / organizações (para os parâmetros database / organization)
read.organization.get_organization_cardFicha da organização: CNPJ/IE/registro, CNAE, órgão fiscal, endereços, conta bancária, diretor e contador-chefe
read.schema.list_entities / read.schema.describe_entityMapa de objetos da base e campos de um objeto específico (de $metadata)
read.counterparty.find_counterparty / read.counterparty.get_counterpartyBusca de contraparte (por nome/CNPJ) e sua ficha
read.document.search_documents / read.document.get_documentBusca de documentos e documento com parte tabular
read.analytics.get_debtors / read.analytics.get_inventoryContas a receber (cta. 62) / saldos de mercadorias (cta. 41/10/43), pode ser em data passada (asOf)
read.analytics.get_sales / read.analytics.get_cashflowVendas do período / fluxo de caixa (banco + caixa)
read.analytics.get_sales_breakdown / read.analytics.get_purchases_breakdownVendas/compras com detalhamento por contraparte, mês, contrato, categoria (PJ/PF/…)
read.analytics.get_payments_breakdownEntradas/saídas por tipo de operação, mês, contraparte, item de fluxo de caixa — «quanto pagamos a PF no ano», «juros de depósito»
read.analytics.get_taxes_paidImpostos e contribuições pagos no período, com detalhamento por tipo de imposto
read.analytics.get_deal_historyCronologia de movimentações de um negócio (código na finalidade do pagamento) ou contrato
read.counterparty.get_customer_history / read.counterparty.get_supplier_historyHistórico de liquidações mútuas com comprador / fornecedor
read.system.health_checkVerificação de conexão e autenticação

Gravação (✍️ exige habilitação, funciona via dry-run → confirm=true):

FerramentaO que faz
write.counterparty.create_counterpartyContraparte (+ telefone/e-mail/endereço/registro)
write.counterparty.create_bank_account / write.counterparty.create_contact_personConta bancária (banco por código) / contato (diretor)
write.catalog.create_nomenclatureItem (pasta, código, indicador de serviço)
write.catalog.create_contractContrato (tipo, número, moeda, tipo de preço, responsável da contraparte)
write.sales.create_invoice / write.purchase.create_supplier_invoiceFatura ao comprador / fatura de pagamento ao fornecedor (não lançadas)
write.purchase.create_purchase / write.sales.create_shipmentEntrada de fornecedor / venda ao comprador
write.warehouse.create_return_from_customer / write.warehouse.create_return_to_supplierDevolução de mercadorias do comprador / ao fornecedor
write.warehouse.create_transferTransferência de mercadorias entre almoxarifados
write.warehouse.create_surplus / write.warehouse.create_writeoffEntrada / baixa de mercadorias
write.warehouse.create_inventoryInventário de mercadorias no almoxarifado
write.sales.create_actVenda de serviços (termo)
write.sales.create_services_actTermo de prestação de serviços (receitas/despesas por grupo de itens)
write.money.create_payment / write.money.create_payout_orderPagamento do comprador (entrada na conta corrente) / ordem de pagamento
write.money.create_bank_writeoffBaixa da conta bancária (pagamento de saída, tipo de operação obrigatório)
write.money.create_cash_receipt / write.money.create_cash_paymentRecibo / ordem de pagamento de caixa (RPC / OPC)
write.sales.create_issued_invoice / write.purchase.create_received_invoiceNota fiscal emitida / recebida (com base na venda / entrada)
write.entity.create_folder / write.entity.move_to_folderPasta (grupo) do diretório / movimentação para pasta
write.counterparty.update_counterparty / write.catalog.update_nomenclature / write.entity.update_entityAlteração de atributos (PATCH)
write.document.copy_documentDocumento com base em um existente — com todos os atributos
write.document.update_document_lines / write.document.add_document_line / write.document.remove_document_lineEdição de linhas de documento
write.document.post_documentLançar / desfazer lançamento (o 1C gera os lançamentos)
write.entity.mark_for_deletionMarcar para exclusão / desmarcar (exclusão suave)

Todas as ferramentas foram testadas em base real 1C:Contabilidade Empresarial 3.0.

Linhas de documentos de venda e compra aceitam:

  • content — atributo «Conteúdo». É esse texto que é impresso na fatura e no documento universal de transferência («Serviços conforme anexo nº 4 de 01/10/2025 ao contrato nº 87 … referente a julho de 2026»). O próprio 1C não o preenche, então para serviços defina explicitamente.

  • incomeAccount / expenseAccount — contas de receitas e despesas pelo código como no 1C (90.01.2, 90.02.2) ou via Ref_Key. Elas também podem ser definidas para o documento inteiro. Prioridade: linha → documento → registro «Contas contábeis de itens» → 90.01.1 / 90.02.1. As contas se aplicam a documentos de venda; fatura de pagamento e entrada não as utilizam.

  • orgBankAccount (fatura ao comprador, venda, termo) — conta bancária da organização, que é impressa como dados para pagamento: nome, número da conta ou Ref_Key. Sem indicação, é usada a conta principal da organização.

write.document.add_document_line e remove_document_line remontam a parte tabular, preservando os atributos das linhas anteriores — conteúdo, contas contábeis, grupo de itens. update_document_lines substitui as linhas por completo, portanto nelas os atributos são definidos novamente. As linhas são gravadas na parte tabular que está preenchida no documento: no termo de serviços é «Serviços», no documento de mercadorias — «Mercadorias».

Documentos mensais recorrentes são mais fáceis de emitir via write.document.copy_document: ele usa o documento anterior como modelo e transfere todos os atributos, incluindo os que não estão nos esquemas de create_* — conta bancária, responsável, endereço de entrega, condições adicionais da fatura. Altere pela data (date), atributos do cabeçalho (fields) e edições de linhas por número (lines).

Segurança

Por padrão, o servidor opera somente em leitura. A gravação é habilitada conscientemente, por meio de dois protetores independentes:

  1. Interruptor global READ_ONLY=false.
  2. Flag por base ODATA_DB_<ИМЯ>_WRITABLE=true — bases sem ele permanecem somente leitura mesmo com o global desativado. Assim, é possível abrir gravação em uma base (ex.: MEI) e proteger outras (ex.: LTDA).

Adicionalmente, na gravação:

  • dry-run por padrão — a ferramenta primeiro mostra o que será criado e só grava quando confirm=true;
  • exclusão suave — write.entity.mark_for_deletion marca o registro (como no 1C); não há DELETE definitivo;
  • no lado do 1C, em "Composição OData", apenas os objetos necessários são habilitados, e o usuário do 1C deve ter permissões de escrita.

Privacidade dos dados. O servidor é um processo local na sua máquina: ele acessa apenas o seu banco 1C (via autenticação Basic) e entrega os dados ao seu cliente MCP. Não há servidores de terceiros do projeto na cadeia. Se você usar um modelo local (Ollama, LM Studio), os dados do 1C não saem da sua rede. Os segredos vêm apenas de .env (ou do bloco env do config); a senha e o cabeçalho de autorização não aparecem nos logs.

Como habilitar a gravação — docs/CONNECTING.md → Habilitando gravação.

Várias bases e várias organizações

São casos diferentes:

  • Várias bases separadas (endereços OData diferentes) — um único servidor atende todas; o nome da base é passado pelo parâmetro database. Configuração em .env — veja docs/CONNECTING.md. Exemplo de consulta: "compare a receita de buh e torg em maio".
  • Várias organizações (pessoas jurídicas) na mesma base — não é necessária uma conexão separada, funciona o filtro organization. Exemplo: "saldos da organização Romashka".

Limitações

Vale saber antecipadamente:

  • Requer OData publicado. O servidor funciona apenas através da interface padrão OData do 1C. Ele não usa nem exige acesso direto a SQL, conexões COM ou arquivos do servidor 1C.
  • O objeto deve estar na "Composição OData". Se o objeto não estiver publicado, a ferramenta retorna uma dica educada com o nome do objeto e o caminho para adicioná-lo. Publique conforme necessário.
  • Configuração alvo — Contabilidade Empresarial 3.0. Os nomes dos objetos são detectados automaticamente a partir de $metadata, mas a análise (contas a receber/saldos) e as contas contábeis dos documentos são projetadas para o plano de contas do BP 3.0. Em UT/ERP e configurações personalizadas, a leitura de diretórios/documentos funciona, mas a análise contábil pode exigir ajustes.
  • Os documentos são criados não lançados. Os lançamentos são gerados pelo próprio 1C ao lançar (write.document.post_document ou manualmente) — o servidor não "desenha" lançamentos diretamente.
  • Operações rotineiras não são criadas. Fechamento de mês, depreciação, cálculo de custo/ICMS são gerados pelo processamento "Fechamento de Mês" com seus próprios algoritmos — não é possível executá-los via OData. A leitura (read.document.search_documents/read.document.get_document) é possível.
  • Pagamento (write.money.create_payment). O documento é criado e lançado, mas os lançamentos contábeis Dt 51 Kt 62 são gerados apenas se a conta contábil (51) estiver configurada para a conta bancária da organização — isso é uma configuração no 1C.
  • OGRN e outros atributos adicionais. São gravados apenas se o "atributo adicional" correspondente estiver cadastrado na base (Administração → Atributos adicionais). Caso contrário, a ferramenta informa honestamente que não há onde gravar.
  • Endereço é gravado como texto de exibição (não um endereço FIAS estruturado).
  • Paginação e limites. Para não exportar milhares de linhas, há um tamanho de página e um máximo de proteção (ODATA_PAGE_SIZE / ODATA_MAX_ROWS); grandes seleções são truncadas com uma marcação.

Como funciona

Processo local em Node.js, comunica-se com o cliente via protocolo MCP através de stdio, e com o 1C via HTTP para OData (autenticação Basic). Stack: Node.js 20+, TypeScript (strict), @modelcontextprotocol/sdk oficial, fetch nativo, zod (validação), pino (logs em stderr), fast-xml-parser (parse de $metadata).

O mapa de objetos é construído automaticamente a partir de $metadata da base e é cacheado; as consultas são montadas por um builder type-safe. Várias bases — cada uma tem seu próprio cliente e cache de metadados.

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 no OData 1C. O 1C não decodifica + como espaço dentro de $filter (responde 400), então o query-string é montado via encodeURIComponent (espaço → %20), e não URLSearchParams.
  • Contas contábeis dos documentos não são preenchidas automaticamente via OData (isso é feito pelo formulário do 1C ao selecionar o item) — o servidor as obtém do registro "Contas contábeis de itens", com fallback para os códigos padrão do plano de contas.
  • Logs e stderr. stdout é usado pelo JSON-RPC, então os logs vão para stderr — mas apenas no terminal. Sob um cliente MCP (quando stdin é pipe), os logs são gravados no arquivo <tmpdir>/1c-odata-mcp/server.log, para não quebrar clientes que interpretam qualquer saída em stderr como erro fatal. Para retornar os logs ao stderr: MCP_LOG_STDERR=1.
  • Respostas tipadas. Todos os 56 instrumentos declaram outputSchema — clientes que suportam structuredContent (não apenas JSON textual) podem tipar a resposta sem precisar fazer parse do texto.
  • Nomes dos instrumentos. dot-notation de três segmentos: <read|write>.<категория>.<имя> (ex.: read.analytics.get_debtors, write.sales.create_shipment) — agrupa os instrumentos por categoria e mostra imediatamente se é leitura ou gravação.

Perguntas frequentes (FAQ)

O cliente MCP "trava" / a consulta expira por timeout. Se até chamadas pequenas travam (read.system.health_check, read.system.list_databases) — quase sempre é um processo MCP travado (no Claude Desktop resolve com reinicialização completa do aplicativo, Cmd+Q e abrir de novo), não a base. Um read.system.health_check saudável responde em um segundo.

Informo outra base, mas ela está "indisponível" / só uma responde. O parâmetro database é o nome de read.system.list_databases (campo name, ex.: ooo), não o "nome amigável" (label, ex.: "OOO Romashka"). Use o nome.

Resposta vazia / "0 objetos". A Composição OData não está configurada — adicione os objetos necessários no 1C (veja docs/ODATA-SETUP.md e docs/CONNECTING.md).

Está lento. Isso é latência do seu 1C / hospedagem, não do Claude: seleções anuais em bases "pesadas" podem levar 10–30 segundos. Pergunte com um período mais curto (trimestre/mês) — a resposta chega em segundos.

Preciso de acesso SQL ou COM da base? Não. O servidor usa apenas OData — nada é instalado dentro do 1C, e ele não acessa SQL diretamente.

É seguro deixar a IA acessar a base de produção? Por padrão — somente leitura. A gravação é habilitada por duas flags independentes e funciona com pré-visualização (dry-run) e confirmação. Não há exclusão física (apenas marcação). Veja Segurança.

Qual 1C serve? Qualquer uma com OData habilitado — nuvem (Scloud/1cFresh), servidor com SQL ou base de arquivos local. Passo a passo para cada caso — docs/ODATA-SETUP.md.

Agradecimentos

  • @Alexsab — trabalho com documentos na 0.4.0: copy_document, "Conteúdo" nas linhas, contas de receitas/despesas explícitas, seleção da conta bancária da organização, classe separada de erros de entrada. E, o mais valioso, bugs encontrados em base real que não são pegos por testes unitários: a edição de linhas do ato saía fora da sua parte tabular, e a seleção da conta bancária estava quebrada silenciosamente.

Encontrou um erro ou falta documentação — issue e PRs são bem-vindos. Achados em bases reais são especialmente valiosos: as configurações 1C diferem, e o que funciona em uma, em outra responde com erro 500.

Licença

MIT. Projeto aberto — use, faça fork, envie issues e PRs: https://github.com/evilbruce666/1c-odata-mcp.

⭐ Se o conector foi útil — dê uma estrela no GitHub e conte no Discussions quais perguntas você faz ao seu 1C. É a melhor motivação para desenvolver o projeto.