thingworx-mcp-server

doubleSlashde/thingworx-mcp-server

3.2

If you are the rightful owner of thingworx-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The ThingWorx MCP Server is an experimental Spring Boot-based server designed to expose ThingWorx functionalities as AI-friendly tools and APIs, featuring Redis-backed caching and flexible deployment configurations.

ThingWorx MCP Server

LLM-based agent for ThingWorx: Architecture and implementation with MCP

A Spring Boot-based server that exposes ThingWorx as a set of AI-friendly tools and APIs, with Redis-backed caching and flexible configuration for cloud or local deployment.

Disclaimer: This repository is an experimental project created for evaluation and testing purposes only. It is not intended for production use and comes without any warranties or guarantees.

Features

  • REST API for interacting with ThingWorx Things, Properties, Services, and Collections
  • AI Tooling: Annotated methods for use with Spring AI MCP
  • Caching: Redis-backed, with toggle to enable/disable at runtime
  • Configurable: All important settings can be set via environment variables
  • Docker-ready: Includes Dockerfile and docker-compose for easy local or cloud deployment

Quick Start

1. Prerequisites

  • Docker (for local dev/testing)
  • Access to a ThingWorx instance (local or remote)

2. Run with Docker Compose (Recommended)

This will start both Redis and the MCP server, wired together. Adapt env variables in docker-compose.yaml to configure it for your environment (see below for explanation). And then run

docker-compose up --build
  • The MCP server will be available at http://localhost:8081
  • Redis will be available at localhost:6379 (internal to the Docker network)
Environment Variables (override as needed)
  • THINGWORX_BASE_URL (default: http://localhost)
  • THINGWORX_APP_KEY (your ThingWorx app key)
  • CACHE_ENABLED (true or false, default: true)
  • SERVER_PORT (default: 8081)
  • REDIS_HOST, REDIS_PORT, REDIS_PASSWORD (default: redis, 6379, empty)
  • MCP_SERVER_* (see below for advanced MCP endpoints)

3. Run Locally (without Docker - needs Java 21+, Apache Maven)

  • Start Redis yourself (e.g. docker run -p 6379:6379 redis:7-alpine)
  • Set environment variables as needed
  • Run the Spring Boot app:
mvn spring-boot:run

API Overview

The server exposes REST endpoints (and AI tool endpoints) for:

  • Things: List, get metadata, check existence
  • Properties: List properties, get property value
  • Services: List services, get parameters, invoke service
  • Collections: List built-in ThingWorx collections (Things, Users, etc.)

All endpoints are available under the configured MCP endpoints (see MCP_SERVER_ENDPOINT, default /mcp).

Caching

  • By default, all tool methods use Redis for caching (see @Cacheable annotations in the code).
  • To disable caching (for debugging or dev), set CACHE_ENABLED=false.
  • Cache TTL and Redis connection are configurable via env vars.

Advanced: Customizing MCP Endpoints

You can change the MCP endpoints via these env vars:

  • MCP_SERVER_ENABLED (default: true)
  • MCP_SERVER_TYPE (default: SYNC)
  • MCP_SERVER_PROTOCOL (default: STREAMABLE)
  • MCP_SERVER_SSE (default: /sse)
  • MCP_SERVER_ENDPOINT (default: /mcp)
  • MCP_SERVER_SSE_MESSAGE_ENDPOINT (default: /mcp/message)