mcpx

mcpx-mcp-server provides a real-time bridge between generative AI prompts and Mitsubishi PLC devices. It uses the McpX library (via NativeAOT) to read and write PLC addresses, and exposes those addresses through a named device layer so AI agents can operate devices by friendly names instead of raw addresses. You can define device mappings in app/src/address-comment.json and configure PLC connection details in app/src/.env. Start the service with Docker Compose, then interact with the server using the provided Gemini CLI configuration and prompts such as Start Conveyor A, Stop Conveyor A, or Open Gate A and then start Conveyor A. The server supports reading statuses, writing outputs, and combining actions via natural-language instructions, for example: "Open Gate A and then start Conveyor A" or "Set the target production count to 9999."

To use the service, ensure your AI environment can reach http://localhost:3000/mcp (as configured in Gemini CLI settings). The server translates natural-language instructions into PLC read/write operations using the predefined device definitions, so you can rely on named entities like Conveyor A Start Command or Gate A Status rather than raw addresses.

Prerequisites

• Docker and Docker Compose installed on your machine
• Git to clone the repository

Step 1: Clone the repository

• git clone https://github.com/YudaiKitamura/mcpx-mcp-server.git
• cd mcpx-mcp-server

Step 2: Configure PLC connection and devices

• Edit PLC connection in app/src/.env: PLC_IP=192.168.12.88 # PLC IP address PLC_PORT=10000 # PLC port number IS_ASCII=false # PLC communication mode (true: ASCII, false: Binary) IS_UDP=false # PLC communication protocol (true: UDP, false: TCP)

• Edit or add device definitions in app/src/address-comment.json to map addresses to friendly names, e.g.: [ { "address": "M0", "name": "Conveyor A Start Command", "comment": "true = run, false = stop" }, { "address": "M1", "name": "Conveyor A Status", "comment": "true = running, false = stopped" }, { "address": "M2", "name": "Gate A Open Command", "comment": "true = open, false = closed" }, { "address": "M3", "name": "Gate A Status", "comment": "true = open, false = closed" }, { "address": "D0", "name": "Production Count", "comment": "short type" } ]

Step 3: Start the MCP server

• Ensure Docker Compose is available, then start:

docker compose up -d

Step 4: Verify operation

• Open http://localhost:3000/mcp to reach the MCP API endpoint (if you have a UI or client).
• Validate that device names map correctly to PLC addresses using the provided prompts.

Step 5: Optional Gemini CLI configuration (for AI integration)

• On macOS/Linux, settings live under your home directory: Mac: /Users/{username}/.gemini/settings.json Linux: /home/{username}/.gemini/settings.json Windows: C:\Users{username}\.gemini\settings.json

• Add the MCP server entry:

{
  "security": {
    "auth": {
      "selectedType": "oauth-personal"
    }
  },

  "mcpServers": {
    "mcpx": {
      "httpUrl": "http://localhost:3000/mcp"
    }
  }
}

Notes and tips:

• If you modify PLC connection details or the device definitions, restart the MCP server to apply changes.
• The system relies on named device definitions for ease of use; ensure app/src/address-comment.json accurately reflects the devices you intend to control.
• The Gemini CLI example shows how to configure a client to connect to the MCP server; adjust paths if you use a different AI integration tool.
• For troubleshooting, check Docker Compose logs with: docker compose logs mcpx and examine app/src/.env and app/src/address-comment.json for inconsistencies.
• The HTTP endpoint is intended for integration with AI agents; ensure network access and any required authentication are configured according to your deployment environment.