Basis

@basis1/mcp

AI エージェントのための Excel エンジンです。 AI エージェントが Excel モデルを読み取り、確認し、編集できるようにします。

Basis のための MCP サーバーです。Claude、Cursor、その他の MCP クライアントが Excel ワークブックを解析し、数式を評価し、依存関係を追跡できます。また、ワークブックをセッションとして開き、入力値を変更して結果を読み取ることもできます。

すべてのツールは Basis API 上で動作します。 Basis API キーとネットワーク接続が必要です。また、ツールに渡すワークブックは https://api.basis1.tech の Basis API にアップロードされます。アップロードされるデータをご覧ください。

インストール

Node.js 20.19 以降と Basis API キーが必要です。Basis API キーは、basis1.tech/settings のアカウント設定でご自身で作成してください。以下の各スニペットは npx でサーバーを起動します。初回起動時にパッケージがダウンロードされます。

Claude Desktop

Settings → Developer → Edit Config を開き、以下を claude_desktop_config.json に追加してから、Claude Desktop を再起動してください。

{
  "mcpServers": {
    "basis": {
      "command": "npx",
      "args": ["-y", "@basis1/mcp"],
      "env": {
        "BASIS_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add basis --env BASIS_API_KEY=your-api-key -- npx -y @basis1/mcp

すべてのプロジェクトで使用するには --scope user を追加してください。プロジェクトの .mcp.json を通じて共有するには --scope project を追加してください。共有ファイルでは、各ユーザーのキーをそれぞれの環境から取得するために、"BASIS_API_KEY": "${BASIS_API_KEY}" と記述してください。

Cursor

これを ~/.cursor/mcp.json、またはプロジェクト内の .cursor/mcp.json に追加してください。

{
  "mcpServers": {
    "basis": {
      "command": "npx",
      "args": ["-y", "@basis1/mcp"],
      "env": {
        "BASIS_API_KEY": "your-api-key"
      }
    }
  }
}

その他の MCP クライアント

コマンドに npx、引数に -y @basis1/mcp を指定して stdio サーバーを設定し、環境変数に BASIS_API_KEY を設定してください。Windows でクライアントから npx を直接起動できない場合は、コマンドに cmd、引数に /c npx -y @basis1/mcp を指定してください。

インストール不要：ホスト型エンドポイント

カスタムヘッダーを使った HTTP 経由のリモート MCP サーバーにクライアントが対応している場合、このパッケージを実行する代わりに、ホスト型エンドポイントへ直接接続できます。

{
  "mcpServers": {
    "basis": {
      "type": "http",
      "url": "https://api.basis1.tech/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

Claude Code では、claude mcp add --transport http basis https://api.basis1.tech/mcp --header "Authorization: Bearer your-api-key" を実行してください。

同じツールを利用できますが、お使いのコンピューター上のファイルは読み取れません。path の代わりに url または base64 を渡してください。このパッケージは、お使いのコンピューター上のファイルを読み取ってアップロードすることで、path に対応します。

設定

変数	デフォルト	説明
BASIS_API_KEY	なし（必須）	Basis API キーです。設定されていなくてもサーバーは起動しますが、すべてのツールでキーが不足していることが通知されます。
BASIS_BASE_URL	https://api.basis1.tech	使用する Basis API です。セルフホスト型サーバーなどを指定できます。localhost を指す場合を除き、キーが暗号化されずに送信されることがないよう、https:// を使用する必要があります。
BASIS_MCP_MAX_FETCH_BYTES	200000000	url を渡したときにツールがダウンロードするワークブックの最大サイズです。

キーの以前の名称である BASIS_TOKEN も引き続き使用できますが、名称を変更するよう通知が記録されます。

設定が無効な場合、サーバーは起動しません。修正方法が stderr に書き込まれ、MCP クライアントのサーバーログに表示されます（Claude Desktop：Settings → Developer、または macOS の ~/Library/Logs/Claude/mcp-server-basis.log）。MCP プロトコルには stdout が使われるため、サーバーは診断情報を stderr にのみ書き込み、キーを表示することはありません。

npx -y @basis1/mcp --help でこれらの設定を確認でき、--version でバージョンが表示されます。

ツール

ワークブックの入力には、path（お使いのコンピューター上のファイル）、url、base64 のいずれか1つを指定してください。

解析

• parse_workbook：ブックをNDJSONレコード（workbook_meta、sheet、cell、edge、image、image_summary、audit）として返します。大きなファイルはバックグラウンドジョブとして実行され、完了するまで自動でポーリングされます。
• submit_job：解析ジョブを開始し、待機せずにハンドル（job_id、status_url、stream_url）を返します。
• get_job_status：ジョブのステータスを取得します。
• stream_job：完了したジョブのNDJSON出力を返します。必要に応じて、レコードsince以降を指定できます。
• diff_workbooks：2つのブック間のセル単位の差分（追加、削除、変更されたセル（値および／または数式））を返し、書式のみの変更は別に一覧表示します。before_*とafter_*の入力、およびinclude_formatを受け取ります。

数式

• evaluate_formula：渡したセル値を使って1つのExcel数式を評価します。例：{"formula": "NPV(0.08,A1:A5)", "data": {"A1": 100, ...}}。財務、統計、検索、動的配列の関数を含む278個のExcel関数をサポートしています。

ファイルの再計算

• recalc_workbook：.xlsx（path、url、またはbase64）を受け取り、すべての数式セルに計算済みの値を保存して返します。エラーの概要も同じように返されます。openpyxl（または、計算結果を保存せずに数式を保存するライブラリ）でブックを作成または編集した後に呼び出してください。これを実行しないと、pandas、openpyxlのdata_only=True、その他Excel以外のリーダーではセルが空に見えます。これはLibreOfficeのrecalc.pyを実行する処理に代わるものです。output_pathを渡すとコンピューターに結果を書き込みます。入力と同じパスを指定し、overwrite: trueを設定すると、ファイルをその場で再計算します。計算のためにファイルはアップロードされますが、保存されません。

ファイルを返すどちらのツールも、Basisがモデル化しない要素（スタイル、チャート、画像、データの入力規則、条件付き書式、定義名、コメント、.xlsm内のVBA）をバイト単位で引き継ぎます。保持できない要素はsummary.warningsに記載されます。これには、セル内のテキストに対する単語単位の書式、What-Ifデータテーブル、複数セル配列数式のキャッシュ済み計算結果が含まれます。Basisで計算できない数式は、通知なしに空白で保存されるのではなく、summary.uncomputedに記載されます。

ブックセッション。 セッションを使うと、Basis API上で1つのブックを開いたまま、段階的に変更できます。

• create_session：path、url、base64 または Library（library_file_id）からブックを開くか、空のブックを開始します。省略可能な calc を指定すると、反復計算が有効になります。ローカルの path は1つのリクエスト内で送信されるため、約24 MBを超えるファイルはまだセッションとして開けません。大きなファイルには parse_workbook を使用してください。
• list_sessions、close_session。
• set_inputs：定義名またはセル参照で値や数式を設定して再計算し、変更された名前付き出力を報告します。
• get_outputs：名前、セル参照、範囲（Sheet1!H2:H18）、またはすべての定義名を指定して、計算済みの値を読み取ります。
• define_variable：定義名を作成するか、参照先を変更します。
• add_sheet：空のブックにシートを追加します。
• rename_sheet：シートの名前を変更します。そのシートを参照する数式、定義名、入力規則も新しい名前に追従します。
• set_calc_settings：循環参照を含むモデルの反復計算を有効または無効にします。
• inspect_model：シート、定義名、計算設定、統計情報を確認します。依存関係グラフも任意で含められます。
• get_cell_formula、get_formula_range：1つのセルまたは範囲の数式と値を取得します。
• trace_dependencies：セルの参照元と参照先を、最大5階層まで追跡します。
• audit_workbook：構造監査（エラー、無効な参照、循環参照、名前付き範囲）を実行します。
• commit_session、restore_session：名前付きチェックポイントとロールバックを行います。
• export_workbook：セッションを再計算し、各数式の計算済みの値をファイルに保存した .xlsx と、数式エラー（#REF!、#DIV/0!、#NAME? とシート名およびセル）の概要を返します。base64ではなくコンピューター上のファイルとして書き込むには、output_path を指定してください（既存ファイルを置き換えるには overwrite: true を指定します）。
• snapshot_session：現在のブックを .xlsx のバイトデータ（base64）として返します。概要は含まれません。export_workbook の使用を推奨します。
• save_to_library：ブックを Basis Library に新規ファイルまたは新しいバージョンとして保存します。

ツールのエラーは、isError が設定され、{"code", "message", "status"} 形式のJSON本文を含むツール結果として返されます。たとえば、missing_api_key、unauthorized、network_error、session_not_found、またはAPIのエラーコードが返されます。

アップロードされるデータ

• 解析と差分比較： ブックは Basis API に送信されます。解析ジョブとその結果はサーバーのメモリ内にのみ保持され、15分後に期限切れになります。
• 数式： 数式と、渡したセルの値が Basis API に送信されます。
• セッション： セッションの作成時にブックがアップロードされ、作業中は Basis API 上に保持されます。セッションは30分間使用されない場合、または close_session を呼び出した場合に終了します。サーバーの再起動後もセッションを維持するため、状態はプライベートクラウドストレージにもチェックポイントとして保存され、チェックポイントは1日以内に削除されます。
• Library： save_to_library で保存したブックは、削除するまで Library に保管されます。
• コンピューター上のファイル： ツールは渡した path のファイルを読み込み、その内容をアップロードします。それ以外のファイルは読み込みません。
• URL： このパッケージは、parse_workbook、submit_job、または diff_workbooks に渡した url をお使いのマシン上でダウンロードし、そのバイトデータをアップロードします。セッションの場合、URLは Basis API 自体がダウンロードします。

すべての通信にはHTTPSが使用され、APIキーは Authorization ヘッダーに含まれます。ブックをお使いのマシンの外に出せない場合は、このサーバーで使用しないでください。

開発

このリポジトリをチェックアウトした状態から：

(cd ../sdk && npm ci && npm run build)  # @basis1/parse, linked as file:../sdk
npm ci
npm run build                            # typecheck, then bundle dist/index.js
npm test                                 # unit, hosted forwarding and stdio handshake tests
npm run test:pack                        # pack, install in a temp dir, MCP handshake over stdio

セルフホスト可能なサーバーなど、別の Basis サーバーに対してビルドを実行するには：

BASIS_API_KEY=devtoken BASIS_BASE_URL=http://localhost:8080 node dist/index.js

パッケージのビルド方法

dist/index.js は、@modelcontextprotocol/sdk と zod（どちらも MIT ライセンス）を含む単一の esbuild バンドルです。ランタイム依存関係としてこれらをインストールすると、初回の npx 実行ごとに 95 個のパッケージ（23 MB）がインストールされます。その中には、stdio サーバーでは使用しない Web サーバーフレームワークも含まれます。バンドルすることで、npx がインストールするパッケージは 2 個になり、テスト済みの正確なバージョンが実行されます。ライセンステキストは dist/THIRD_PARTY_LICENSES.txt に同梱され、バンドルしたパッケージに許諾的なライセンスが適用されていない場合、ビルドは失敗します。

@basis1/parse はバンドルされていない、実際のランタイム依存関係です。リポジトリでは file:../sdk を指定しています。リリースプロセスでは公開前にこれを ^<sdk version> に書き換えます。また、scripts/check-publishable.mjs はローカルパスが残っているパッケージを拒否します。

リリース

リリースはメンテナーが公開します。変更が両方のパッケージに関わる場合は、SDKを先にリリースし、その公開済みのSDKバージョンに依存するMCPサーバーを次にリリースします。version は package.json と server.json の間で同期されています。

MCP Registry

server.json では、このサーバーを MCP Registry 向けに tech.basis1/mcp として記述しており、package.json の mcpName が npm パッケージを Registry に紐付けています。tech.basis1/ 名前空間は個人の GitHub アカウントではなく basis1.tech ドメインに属しているため、Registry は DNS を通じてこれを検証します。自動で登録されることはありません。

メンテナーは npm への公開後、mcp-publisher login dns --domain basis1.tech でログインし、各リリースを Registry に登録します。tech.basis1/ 名前空間は basis1.tech の DNS レコードを通じて検証されます。

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。