thingworx

ThingWorx MCP Server exposes ThingWorx resources (Things, Properties, Services, and Collections) through MCP-compatible endpoints and AI tooling. It exposes a REST API for interacting with ThingWorx entities and wraps these calls behind AI-friendly tools that can be invoked by an MCP-enabled agent. Caching is Redis-backed and configurable at runtime, helping to speed up repeated queries and avoid unnecessary calls to ThingWorx. The server is designed to run locally via Docker Compose or locally with Java (Spring Boot) for development and testing. You can customize endpoints and enable/disable features via environment variables.

You can access the MCP endpoints by default at /mcp (configurable via MCP_SERVER_ENDPOINT) and you can also use the provided SSE/stream endpoints to receive live updates. The REST API covers listing Things, fetching their metadata, reading and invoking Services, and listing built-in ThingWorx collections. The server also exposes AI tooling endpoints that can be discovered and used by an MCP-enabled agent to reason about and perform actions in ThingWorx.

Prerequisites:

• Docker and Docker Compose for quick setup
• Optional: Java 21+ and Maven if you want to run the Spring Boot app locally without Docker

Install and run with Docker Compose (recommended):

1. Create or edit docker-compose.yaml to configure the environment variables (ThingWorx URL, app key, Redis connection details, etc.).
2. Start the services:

docker-compose up --build

3. Access the MCP server at http://localhost:8081 (default). Redis will be accessible on the internal Docker network at port 6379.

If you prefer running locally without Docker:

1. Ensure Java 21+ is installed and Maven is available.
2. Set environment variables to support Redis and ThingWorx access (e.g., THINGWORX_BASE_URL, THINGWORX_APP_KEY, REDIS_HOST, REDIS_PORT).
3. Run the Spring Boot application:

mvn spring-boot:run

4. The server will start on port 8081 by default unless overridden via SERVER_PORT.

Tips and common issues:

• Ensure ThingWorx BASE URL is reachable from the container or host where the server runs.
• If Redis is not reachable, double-check REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD (empty by default).
• Set CACHE_ENABLED=false to disable caching during debugging or dev.
• MCP endpoints are configurable through environment variables prefixed with MCP_SERVER_ (endpoint paths, enablement, protocol, etc.).
• The project uses Spring Boot and Redis caching via @Cacheable; ensure Redis is properly configured when running in production-like environments.
• If you run via Docker Compose, you can adjust docker-compose.yaml to wire in your own ThingWorx instance and Redis settings.