i3x-mcp

A bridge that lets Claude (and any other MCP client) talk to your manufacturing data through the i3X standard — so you can ask plain-English questions about your plant and get real answers.

"What equipment is on the production line?" "What's the current state of pump-101?" "Show me the temperature trend for tank-201 over the last hour." "What feeds into the assembly line?"

Install (5 minutes, no coding required)

1. Install Node.js (if you don't already have it)

Open a terminal and run:

node --version

If you see a version number ≥ 18 (e.g. v20.0.0), you're set. If not, download and install from nodejs.org — pick the "LTS" version.

2. Open Claude Desktop's config file

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it.

3. Add the i3x server

If the file is empty, paste this whole thing:

{
  "mcpServers": {
    "i3x": {
      "command": "npx",
      "args": ["-y", "i3x-mcp@latest"]
    }
  }
}

If the file already has stuff in it, add only the "i3x": { ... } block inside mcpServers (and add the mcpServers block if missing). Mind the commas between JSON keys — that's the #1 reason Claude Desktop reports an invalid config.

4. Restart Claude Desktop

Fully quit (⌘Q on Mac, right-click tray → Quit on Windows) and reopen. The first time you use it, npx downloads i3x-mcp from npm — takes 10-20 seconds.

5. Tell Claude which i3X server to talk to

Start a new chat and say:

"Use the i3x connect tool with baseUrl https://api.i3x.dev/v1"

(That's the public CESMII demo server. For your own deployment, substitute your URL.)

Claude will verify the connection and confirm. From there you can ask normal questions:

"What equipment is at the top of the hierarchy?" "Find anything with 'pump' in the name." "What's the current value of pump-101 and its components?" "Get the last hour of history for pump-101-state, averaged every 5 minutes."

Connecting to a private / authenticated server

If your i3X server requires authentication:

"Connect i3x to https://i3x.mycompany.com/v1 with authScheme bearer and token eyJhbGc..."

Supported auth schemes:

• none (default)
• bearer — uses Authorization: Bearer <token>
• apikey — uses a custom header (default X-API-Key, override with the apiKeyHeader argument)

Connections live for the duration of a Claude Desktop session. To switch servers mid-session, just call connect again.

Persisting connection info via environment variables

If you'd rather not type the connect command each time, pre-set the connection in your Claude Desktop config:

{
  "mcpServers": {
    "i3x": {
      "command": "npx",
      "args": ["-y", "i3x-mcp@latest"],
      "env": {
        "I3X_BASE_URL": "https://i3x.mycompany.com/v1",
        "I3X_AUTH_SCHEME": "bearer",
        "I3X_TOKEN": "eyJhbGc..."
      }
    }
  }
}

What Claude can do

| Tool | What it does | |---|---| | connect | Point the server at an i3X instance. Validates against /info. | | connection_status | Show current baseUrl, auth, and catalog state. | | server_info | Capabilities of the connected i3X server (query/update/subscribe). | | search_objects | Find equipment by name (fuzzy/substring). The main "where is X" tool. | | list_root_objects | Top of the equipment hierarchy. | | refresh_catalog | Re-fetch the object list after new equipment is added. | | get_object | Detailed info on one or more objects (type, parent, relationships). | | read_current_value | Latest value + quality + timestamp, with engineering units when known. | | get_history | Time-range history with optional avg/min/max/count aggregation and bucket (e.g. 5m). Accepts relative times like "last 1h". | | find_related | Graph traversal. Returns related objects grouped by relationship. | | describe_type | ObjectType schema + per-field units (helps Claude interpret raw values). | | watch_values | Bounded live-data window. Internally manages an i3X subscription. |

Writes (update_value, write_history) are off by default. See "Enabling writes" below.

Time inputs

Anywhere a time is accepted (get_history), you can use:

• RFC 3339: 2026-06-12T10:00:00Z
• Relative: 1h, 30m, 7d, last 30m
• Keywords: now, today, yesterday

For startTime, a bare duration means "that long ago." For endTime, the default is now.

Enabling writes (advanced)

Setpoint writes can affect live equipment. Writes are off by default. To enable them, modify your Claude Desktop config to pass --enable-writes:

"args": ["-y", "i3x-mcp@latest", "--enable-writes"]

This exposes update_value and write_history. Both are marked as destructive — Claude will request explicit confirmation before invoking them.

Tuning (environment variables)

| Env var | Default | Purpose | |---|---|---| | I3X_BASE_URL | unset | Optional pre-set baseUrl. If unset, use the connect tool from chat. | | I3X_AUTH_SCHEME | none | none, bearer, or apikey. | | I3X_TOKEN | — | Required when I3X_AUTH_SCHEME is bearer or apikey. | | I3X_APIKEY_HEADER | X-API-Key | Header name used when I3X_AUTH_SCHEME=apikey. | | I3X_WATCH_MAX_SEC | 300 | Hard cap on watch_values duration. | | I3X_RAW_HISTORY_MAX_POINTS | 500 | Cap on raw VQT points returned per element by get_history. |

Troubleshooting

Claude Desktop says "MCP i3x: Server disconnected"

• Check the claude_desktop_config.json is valid JSON (commas, braces).
• Confirm Node.js 18+ is installed and node is on your PATH.
• Open the developer logs in Claude Desktop's "Settings → Developer" panel for details.

Tools return "Not connected to an i3X server"

• Call the connect tool: "Connect i3x to https://..."
• Or set I3X_BASE_URL in the config's env block and restart Desktop.

Connection fails on connect

• The error message will say what failed (e.g. DNS, 401 Unauthorized). Re-check the baseUrl and auth.
• The baseUrl must include the version path, e.g. https://api.i3x.dev/v1.

For developers

Run from source

git clone <this-repo> i3x-mcp
cd i3x-mcp
npm install
npm run build

Point Claude Desktop at the local build:

{
  "mcpServers": {
    "i3x": {
      "command": "node",
      "args": ["/absolute/path/to/i3x-mcp/dist/index.js"]
    }
  }
}

Project layout

src/
  config.ts          # env + CLI parsing
  connection.ts      # connection lifecycle (connect / disconnect / state)
  i3x-client.ts      # HTTP client + i3X types
  catalog.ts         # cached object/type index + fuzzy search (fuse.js)
  time.ts            # relative time parsing
  aggregation.ts     # raw/avg/min/max/count bucketing
  units.ts           # unit extraction + value enrichment
  tools.ts           # all MCP tool registrations
  index.ts           # entry point

Smoke test

node smoke-test.mjs

Spawns the server, walks through connect → search_objects → get_history against the public demo.

Publishing to npm

You'll need an npm account with publish rights to i3x-mcp. Then:

# Patch release (0.1.0 → 0.1.1):
npm run release:patch

# Minor release (0.1.0 → 0.2.0):
npm run release:minor

# Major release (0.1.0 → 1.0.0):
npm run release:major

Each script:

1. Bumps version in package.json.
2. Creates a git commit and tag.
3. Runs prepublishOnly (which builds via tsc).
4. Publishes to the public npm registry.

Push the tag after with git push --follow-tags.

License

MIT — see LICENSE.