MCP Integration

Pendulum exposes an MCP (Model Context Protocol) JSON-RPC 2.0 server over TCP for AI agents.

Resources

Click to download the MCP bridge script and API reference for your agent integration.

Quick Setup

1. Start the MCP server in-game:

   /pendulum mcp start

2. Configure your MCP client to connect to localhost:25566 (default port).

tip

You can customize the port in the Pendulum config screen (Jupiter config GUI). Also you can set MCP to auto-start on game launch for convenience.

When the MCP server is running, the game window title will show " | Shared with AI Agent" (like VS Code's remote indicator). When a script is executing, it shows " | Script Running".

All MCP tool calls are automatically logged to pendulum/logs/mcp_calls.jsonl for post-hoc review.

For VSCode Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "pendulum": {
      "type": "stdio",
      "command": "node",
      "args": ["mcp-bridge.js"],
      "env": {
        "PENDULUM_HOST": "localhost",
        "PENDULUM_PORT": "25566"
      }
    }
  }
}

For Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pendulum": {
      "command": "node",
      "args": ["path/to/mcp-bridge.js"],
      "env": {
        "PENDULUM_HOST": "localhost",
        "PENDULUM_PORT": "25566"
      }
    }
  }
}

For Codex CLI

Create ~/.codex.yaml (or ~/.codex.yml):

mcpServers:
  pendulum:
    command: node
    args:
      - path/to/mcp-bridge.js
    env:
      PENDULUM_HOST: localhost
      PENDULUM_PORT: "25566"

tip

Make sure to use the absolute path to mcp-bridge.js. You can get it by running pwd (macOS/Linux) or cd (Windows) in the Pendulum project directory.

Once configured, run Codex:

codex

Codex will automatically discover the pendulum MCP server and can use all available tools to control Minecraft. See the Agent API Reference for the full tool list.

Available Tools

Tool	Description
pendulum_eval	Execute JavaScript code; returns result or error
pendulum_screenshot	Capture game window screenshot (base64 PNG)
pendulum_gui_elements	Read all visible GUI widgets
pendulum_status	Check if a script is running
pendulum_abort	Stop the current running script

Configuring

In the Pendulum config screen (Jupiter config GUI):

• MCP Enabled: Auto-start MCP server on game launch
• MCP Port: TCP port (default 25566)
• Permissions: Control what scripts can do (chat, break, place, attack, commands)