クイックスタート

注意事項

obniz MCP Server は alpha 版です。仕様や動作は変更される可能性があり、サーバーの可用性や動作の継続性は保証されません。

もっとも簡単な始め方は、obniz が提供するクラウド MCP エンドポイントに MCP クライアントを接続する方法です。

Cloud endpoint

MCP クライアントの URL は https://mcp.obniz.com/mcp、認証は Authorization: Bearer apptoken_xxx です。

1. obniz Cloud を準備する

obniz Cloud で次の準備をします。

Hosted App を作成、または既存の Hosted App を選択します。
操作したい obniz デバイスに Hosted App をインストールします。
Hosted App の App Token を発行します。

App Token は通常 apptoken_ から始まります。このトークンでアプリにインストールされたデバイスへアクセスできるため、外部に公開しないでください。

2. MCP クライアントを設定する

クラウド版では https://mcp.obniz.com/mcp に接続します。

App Token は Authorization: Bearer apptoken_xxx の形式で渡します。

Claude Desktop

claude_desktop_config.json にサーバーを追加します。

{
  "mcpServers": {
    "obniz": {
      "url": "https://mcp.obniz.com/mcp",
      "headers": {
        "Authorization": "Bearer apptoken_xxx"
      }
    }
  }
}

設定ファイルの主な場所は次の通りです。

OS	パス
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

編集後、Claude Desktop を再起動してください。

Claude Code

プロジェクトの .mcp.json など、MCP 設定ファイルにサーバーを追加します。

{
  "mcpServers": {
    "obniz": {
      "type": "http",
      "url": "https://mcp.obniz.com/mcp",
      "headers": {
        "Authorization": "Bearer apptoken_xxx"
      }
    }
  }
}

プロジェクトファイルに設定する場合、実際の App Token を Git にコミットしないでください。

CLI から追加することもできます。

claude mcp add obniz --transport http https://mcp.obniz.com/mcp \
  -h "Authorization: Bearer apptoken_xxx"

Codex CLI

Codex CLI では、App Token を環境変数に入れて HTTP MCP サーバーを追加します。

setx OBNIZ_APP_TOKEN "apptoken_xxx"
codex mcp add obniz --url https://mcp.obniz.com/mcp --bearer-token-env-var OBNIZ_APP_TOKEN

setx で設定した環境変数は、新しく起動した Codex プロセスから有効になります。設定後に Codex を再起動してください。

登録内容は次のコマンドで確認できます。

codex mcp list
codex mcp get obniz

その他の MCP クライアント

次の接続情報を設定してください。

項目	値
URL	`https://mcp.obniz.com/mcp`
Transport	HTTP
認証	`Authorization: Bearer <your_app_token>`

レガシーな SSE トランスポートだけに対応したクライアントを使う場合は、設定を参照してください。

3. 接続を確認する

まずはデバイス一覧が取得できるか確認します。MCP 接続と App Token が正しければ、Hosted App から利用できるデバイスが表示されます。

obnizのデバイスを操作したくて、いまオンラインのデバイスはある？

obniz-mcp - list_devices (MCP)

└ []

現在オンラインのデバイスは0台です。デバイスの電源やネットワーク接続、App Token に紐づく Hosted App を確認してください。

電源入れた

obniz-mcp - list_devices (MCP)

└ [ { "obniz_id": "XXXX-XXXX", ... +6 lines } ]

画面にHello Worldを出したい

obniz-mcp - display_print (MCP)

└ Displayed: "Hello World"

セルフホスト

クラウド版を使わず、自分の環境で MCP サーバーを起動することもできます。

セルフホストの最新の手順、Dockerfile、ソースコードは obniz/obniz-mcp を参照してください。

git clone https://github.com/obniz/obniz-mcp.git
cd obniz-mcp
docker build -t obniz-mcp:latest .
docker run --rm -p 3000:3000 obniz-mcp:latest

起動後、http://localhost:3000/health でヘルスチェックできます。

セルフホスト時も、App Token はサーバー側の環境変数ではなく MCP クライアント側の Authorization ヘッダーで渡します。MCP クライアントの URL は http://localhost:3000/mcp に変更してください。

サーバー自体を開発する場合は、Node.js 18 以上でビルドして起動できます。

npm install
npm run build
npm start