# thingworx-mcp

MCP server for PTC ThingWorx, the IIoT platform. 8 tools for AI agents to read live state and trigger actions across the industrial asset graph.

## What it wraps

The ThingWorx REST API surface that matters to an agent: Things, Properties, Services, ThingTemplates, and the model search index. ThingWorx is the IIoT platform used to wire SCADA, PLCs, MES, and plant equipment into a unified model. This MCP gives an agent the read path for live equipment state and the write path for setpoints and named operations, both env-gated independently because both can affect real industrial equipment.

## Tools (8)

| Tool | Purpose | Env gate |
|---|---|---|
| `list_things` | Inventory all Things in the model | none |
| `get_thing` | Read a Thing's full metadata + surface area | none |
| `read_property` | Read live value of a Property | none |
| `write_property` | Update a Property value | `THINGWORX_ALLOW_WRITE=true` |
| `invoke_service` | Execute a named Service on a Thing | `THINGWORX_ALLOW_INVOKE=true` |
| `list_thing_templates` | Inventory available ThingTemplates | none |
| `get_thing_template` | Read a ThingTemplate's definition | none |
| `search_things` | Free-text search the model | none |

The two gates are independent. An operator can enable property writes (setpoints) without enabling service invocations (which can include emergency stops, PLC commands, downstream workflow triggers), and vice versa.

## Install

```bash
pip install thingworx-mcp
```

## Configuration

ThingWorx is self-hosted. Set:

```bash
export THINGWORX_BASE_URL="https://thingworx.your-company.com"
export THINGWORX_APP_KEY="your-application-key"

# Optional, default false. Enables write_property tool.
export THINGWORX_ALLOW_WRITE="true"

# Optional, default false. Enables invoke_service tool.
export THINGWORX_ALLOW_INVOKE="true"

# Optional, default true. Set to "false" for self-signed dev instances.
export THINGWORX_VERIFY_SSL="false"
```

Generate the appKey in ThingWorx Composer under Security > Application Keys. The MCP uses the appKey header convention (not Bearer).

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "thingworx": {
      "command": "thingworx-mcp",
      "env": {
        "THINGWORX_BASE_URL": "https://thingworx.your-company.com",
        "THINGWORX_APP_KEY": "your-application-key"
      }
    }
  }
}
```

## Use with Hermes

```yaml
mcp:
  thingworx:
    command: thingworx-mcp
    env:
      THINGWORX_BASE_URL: https://thingworx.your-company.com
      THINGWORX_APP_KEY: ${THINGWORX_APP_KEY}
      THINGWORX_ALLOW_WRITE: "true"
```

## Safety model

ThingWorx is wired to real PLCs and real equipment. The MCP defaults to read-only. Property writes and service invocations both require an explicit env opt-in, and the gates are independent so an operator who wants telemetry write capability does not have to also grant service invocation rights.

Failures from the upstream ThingWorx instance are surfaced as structured errors. Network and timeout errors are surfaced with status codes.

## Development

```bash
git clone https://github.com/NoBanks/thingworx-mcp
cd thingworx-mcp
pip install -e ".[dev]"
pytest
```

Tests use respx for HTTP mocking, no live ThingWorx instance required.

## License

MIT. See LICENSE.

## About

Part of a 26 plus MCP server cohort at [github.com/NoBanks](https://github.com/NoBanks), shipped by [@livingagentic](https://x.com/livingagentic). Other industrial MCPs in the same cohort: workday-mcp, veeva-mcp, plaid-mcp, lambda-cloud-mcp. Built using the same factory pattern: env-gated for destructive actions, MIT licensed, install-ready, smoke-tested.