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.