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）。環境変数の代わりに、baseUrl、username、passwordのフィールド（および任意の"writable": true）を含むJSONファイル~/.onec-odata/onec-config.jsonを使用することもできます。ファイルのパスはONEC_CONFIG_PATHで指定します。

手順3 — 最初のリクエスト

Claudeを再起動して、次のように尋ねます。

「1Сデータベースにはどんなカタログとドキュメントがありますか？」

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を構築して検証します	自動で呼び出されます。「6月分」をClaudeが日付に変換し、ツールがフィルターを構築して検証します
odata_query	指定したODataパラメーターでエンティティをクエリします	「6月分の勘定51の残高を表示して」
odata_count	レコード数を取得します。フィルターは任意です	「今年登録された取引先は何件ですか？」
odata_write	エンティティを作成／変更／削除します（POST/PATCH/DELETE）	「取引先を作成して…」—最初にドライランのプレビューを表示します
odata_financial_summary	一般的な財務エンティティを自動検出し、件数を集計します	「勘定、売上、取引先の概要をまとめて」

通常、エージェントはodata_build_query → odata_query／odata_countを自動で組み合わせます。普段の言葉で質問するだけで十分です。

セキュリティ

• デフォルトでは読み取り専用です。 データベース設定の writable フラグ（env ONEC_WRITABLE=true ／ ~/.onec-odata/onec-config.json の "writable": true）は、デフォルトで false です。このフラグがない場合、実際の POST／PATCH／DELETE は1Cに送信されません。
• 書き込みは 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）。これにより、エージェントが誤ってシークレット項目を表示することを防ぎます。
• 推奨事項： 通常の作業には読み取り専用のロールを持つ専用のODataユーザーを1Cに作成してください。書き込み可能なアカウントと ONEC_WRITABLE=true は、必要性を理解したうえでのみ有効にしてください。

要件

• Node.js ≥ 18
• ODataインターフェースを公開した1C:Enterprise（ウェブ公開 → standard.odata）

開発

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

詳細とコントリビューションのルールについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT

---

English (short)

MCP サーバーを通じて、Claude（または任意のMCPクライアント）から1C:Enterpriseデータベースに標準のODataエンドポイント経由でアクセスできます。デフォルトでは読み取り専用（writable: false）です。書き込みは odata_write 経由で行い、writable: true を明示的に有効にして dryRun: false を渡さない限り、必ず最初にドライランを実行します。スプレッドシートへのエクスポートや手書きの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 として公開されており、公式MCP Registryには io.github.alexgrebeshok-coder/onec-odata-mcp として登録されています。