1C OData MCP

onec-odata-mcp

5 分钟内将 1С 接入 Claude

让 Claude（Desktop、Code、任何 MCP 客户端）通过标准 OData 读取 1С:Предприятие 数据库。无需导出到 Excel，也无需手动编写 OData URL——用俄语提问，即可从目录和单据中获取结构化数据。

适用于任何已发布 OData 的 1С 配置（会计、ERP、贸易管理及自定义配置）。

📸 TODO: 添加 5 分钟配置的截图/视频——待使用真实数据库首次运行后添加。

第 1 步 — 安装

无需在本地安装任何内容，首次启动时 npx 会自动获取软件包：

一行命令（发布到 npm 后）：

npx -y onec-odata-mcp

在 MCP 客户端配置中设置 ONEC_BASE_URL、ONEC_USERNAME 和 ONEC_PASSWORD（见下文）。

从源代码安装：

npx -y onec-odata-mcp

（从源代码进行开发时：npm install && npm run build。）

第 2 步 — 连接到 Claude

方案 A — 使用 claude mcp add 命令（Claude Code）：

claude mcp add onec-odata \
  -e ONEC_BASE_URL=https://1c.example.com/your_db/odata/standard.odata \
  -e ONEC_USERNAME=odata_user \
  -e ONEC_PASSWORD=your_password \
  -- npx -y onec-odata-mcp

方案 B — 手动编辑 claude_desktop_config.json（Claude Desktop：Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "onec-odata": {
      "command": "npx",
      "args": ["-y", "onec-odata-mcp"],
      "env": {
        "ONEC_BASE_URL": "https://1c.example.com/your_db/odata/standard.odata",
        "ONEC_USERNAME": "odata_user",
        "ONEC_PASSWORD": "your_password"
      }
    }
  }
}

可直接使用的代码片段位于 examples/claude_desktop_config.json。

可选配置：ONEC_DATABASE（数据库名称提示）、ONEC_METADATA_CACHE_TTL_MS（元数据缓存 TTL，默认为 1 小时）、ONEC_WRITABLE=true（允许通过 odata_write 实际写入；默认为 false）。也可以不使用环境变量，改用 JSON 文件 ~/.onec-odata/onec-config.json，其中包含 baseUrl、username、password 字段（以及可选的 "writable": true）；文件路径通过 ONEC_CONFIG_PATH 设置。

第 3 步 — 首次提问

重启 Claude 并提问：

“数据库中有哪些目录和单据？”

Claude 会调用 odata_list_entities 查看列表，然后根据具体问题自行选择合适的工具——你无需了解 OData 语法。

更多可直接使用的提示词见 examples/prompts.md。

工具

工具	功能	示例问题
odata_config	检查连接状态和配置	“检查 1С 是否已连接”
odata_list_entities	列出所有可用的 OData 实体	“数据库中有哪些目录和单据？”
odata_metadata	获取 $metadata 中的实体类型和集合（缓存，TTL 为 1 小时）	在复杂查询前自动调用
odata_explain_entity	获取指定实体的字段、类型、键和关系	“目录‘交易对手’有哪些字段？”
odata_build_query	根据结构化查询参数构建并验证 $filter/$select/$orderby	自动调用——Claude 会将“6 月份”转换为日期，工具负责构建并验证筛选条件
odata_query	使用现成的 OData 参数查询实体	“显示 6 月份 51 号账户的余额”
odata_count	统计记录数量，可选筛选条件	“今年注册了多少个交易对手？”
odata_write	创建/更改/删除实体（POST/PATCH/DELETE）	“创建一个交易对手……”——先进行 dry-run 预览
odata_financial_summary	自动发现常见财务实体并统计数量	“汇总一下账户、销售和交易对手的数据”

通常 Agent 会自行组合 odata_build_query → odata_query/odata_count，你只需用自己的话提问。

安全性

• 默认只读。 数据库配置中的 writable 标志（环境变量 ONEC_WRITABLE=true / ~/.onec-odata/onec-config.json 中的 "writable": true）默认值为 false。未启用该标志时，不会向 1С 发送真实的 POST/PATCH/DELETE 请求。
• 只能通过 odata_write 写入。 该工具的 dryRun 默认值为 true：始终先预览 {dryRun: true, wouldExecute: …}，不会发起网络调用。要实际写入，必须同时满足：该数据库的 writable: true，并且明确设置 dryRun: false。
• 密码通过 Basic Auth 传递（按 OData 要求，以 base64 编码后放在每个请求的标头中），并存储在 MCP 客户端的配置环境变量中（推荐），或本地文件 ~/.onec-odata/onec-config.json 中。服务器不会在日志中记录密码，也不会在工具响应中返回密码。
• 敏感字段（名称中包含 password、token、apikey、secret 等的字段）会自动从“你可能想找”提示中排除（src/query/fuzzy.ts），避免 Agent 意外突出显示这些字段。
• 建议： 在 1С 中为日常工作创建一个仅有只读权限的独立 OData 用户；只有在明确需要时，才启用具有写入权限的账户和 ONEC_WRITABLE=true。

要求

• Node.js ≥ 18
• 已发布 OData 接口的 1С:Предприятие（Web 发布 → standard.odata）

开发

npm install
npm run build   # type-check + сборка в dist/
npm test

贡献详情和规则请参阅 CONTRIBUTING.md。

许可证

MIT

---

English（简短介绍）

一个 MCP 服务，可让 Claude（或任何 MCP 客户端）通过标准 OData 端点访问 1C:Enterprise 数据库。默认只读（writable: false）；写入通过 odata_write 进行，除非你明确启用 writable: true 并传入 dryRun: false，否则始终先执行 dry-run。无需导出电子表格，也无需手写 OData URL——用自然语言提问，即可获取目录和文档中的结构化数据。

npx -y onec-odata-mcp

通过 ONEC_BASE_URL / ONEC_USERNAME / ONEC_PASSWORD 环境变量进行配置（关于 claude mcp add 和 claude_desktop_config.json 代码片段，请参阅上方的俄语快速入门——JSON 与语言无关）。可选：设置 ONEC_WRITABLE=true 以允许实际写入。已在 npm 上发布为 onec-odata-mcp，并以 io.github.alexgrebeshok-coder/onec-odata-mcp 列入官方 MCP Registry。