obniz Docs Developer obniz MCP Server Quick Start

Quick Start

Notice

obniz MCP Server is currently in alpha. Specifications and behavior may change, and server availability or continued operation is not guaranteed.

The quickest way to start is to connect your MCP client to the cloud endpoint provided by obniz.

Cloud endpoint

Use https://mcp.obniz.com/mcp as the MCP client URL and Authorization: Bearer apptoken_xxx for authentication.

1. Prepare obniz Cloud

Prepare the following in obniz Cloud:

  1. Create or select a Hosted App.
  2. Install the Hosted App to the obniz device you want to control.
  3. Generate an App Token for the Hosted App.

The App Token usually starts with apptoken_. Keep it private, because it grants access to the devices installed to that app.

2. Configure your MCP client

Use https://mcp.obniz.com/mcp for the cloud server.

Pass your App Token as Authorization: Bearer apptoken_xxx.

Claude Desktop

Add the server to claude_desktop_config.json:

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

Common config file locations:

OS Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after editing the file.

Claude Code

Add the server to your project .mcp.json or another private MCP config:

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

If you use a project file, do not commit a real App Token to Git.

You can also add it from the CLI:

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

Codex CLI

With Codex CLI, store the App Token in an environment variable and register the HTTP MCP server:

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

Environment variables set by setx are available to newly started Codex processes. Restart Codex after adding the token.

Check the registered server with:

codex mcp list
codex mcp get obniz

Other MCP clients

Use these connection settings:

Item Value
URL https://mcp.obniz.com/mcp
Transport HTTP
Authentication Authorization: Bearer <your_app_token>

If your client supports only the legacy SSE transport, see Configuration.

3. Verify the connection

First, check whether the client can list devices. If the MCP connection and App Token are valid, the client should show the devices available to the Hosted App.

I want to control an obniz device. Are any devices online?
obniz-mcp - list_devices (MCP)
└ []

There are no online devices. Check the device power, network connection, and Hosted App linked to your App Token.

I turned it on.
obniz-mcp - list_devices (MCP)
└ [ { "obniz_id": "XXXX-XXXX", ... +6 lines } ]
Show Hello World on the display.
obniz-mcp - display_print (MCP)
└ Displayed: "Hello World"

Self-hosting

You can run the MCP server in your own environment instead of using the cloud endpoint.

For the latest self-hosting steps, Dockerfile, and source code, see obniz/obniz-mcp. This page shows only the minimal setup.

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

After startup, use http://localhost:3000/health for a health check.

When self-hosting, the App Token is still passed by the MCP client in the Authorization header, not as a server-side environment variable. Set your MCP client URL to http://localhost:3000/mcp.

If you are developing the server itself, build and run it with Node.js 18 or later:

npm install
npm run build
npm start