mcp-meridis

# mcp-meridis [English](README_EN.md) | ## Overview This program (mcp-meridis) runs on the Meridian project's ecosystem. mcp-meridis is a Python-based web application for controlling robots (mainly walking), managing parameters, monitoring status, and analyzing logs. - **Web UI** button operations allow intuitive control of the robot. - It also works as an **MCP Server**, supporting natural language instructions from AI agents (like Claude). - A **Redis server** is used to exchange data at high speed between multiple programs. [](https://www.youtube.com/watch?v=3TW-UL5gDTo&t=3s) Click the image above to play the YouTube video. ## Main Features - **Walking control based on inverse kinematics (IK) of legs** Pressing buttons like [Home], [Idle], [Start], and [Stop] on the Web UI controls the humanoid's standing posture changes and walking start/stop. Background threads (100Hz) calculate the trajectory of both legs using inverse kinematics and send control commands for each joint angle of the humanoid legs. - **Posture control based on inverse kinematics (IK) of arms** Inputting target coordinates `x, y, z` (in the waist coordinate system, unit: m) performs inverse kinematics and sends control commands for each joint angle of the humanoid arm. - **MCP Server support** By supporting the MCP server (Model Context Protocol Server), it helps AI connect to simulator robots and real robots. Humanoids can be controlled, monitored, and logged using natural language instructions from AI chats like Claude Desktop/Claude Code. - **Status monitoring** Pressing the [Status] button allows checking the walking phase (internal state transition), elapsed time, IMU posture angle, fall judgment, etc. - **Live editing of walking parameters** Editing walking parameters like foot stride, lift amount, waist lateral swing, walking cycle, and forward tilt angle on the Web UI and pressing the [Set to Memory] button reflects the changed parameters immediately. - **Recording and analyzing walking data** Accumulated Meridim arrays (up to 10,000 frames) sent and received during walking can be written out as CSV files. Another analysis tool can generate real-time visualization of joint angles, ZMP estimation, and comparison graphs. - **Data source switching** The data source to be monitored and logged can be switched from the Web UI. - **VLA arm control cooperation** Arm control is possible in cooperation with the SmolVLA inference process of VLA (Vision-Language-Action). ※The program using SmolVLA is not disclosed as of 2026.05. ### Meridian Project Ecosystem > | Component | Developer | Role | > |---|---|---| > | [Meridian](https://meridian-oss.github.io/#project) | Ninagawa123 | Robot communication middleware protocol. Achieves 100 Hz bidirectional communication with ESP32 board and Meridim90 data array | > | [meridis](https://github.com/holypong/meridis) | holypong | Data bridge connecting simulator, real robot, and web application via Redis | > | [merimujoco](https://github.com/holypong/merimujoco) | holypong | MuJoCo physical simulation. Provides Sim2Real/Real2Sim via meridis | > | [mcp-meridis](https://github.com/holypong/mcp-meridis) | holypong | Python application to operate robots with Web UI. Also supports cooperation with AI agents as an MCP server | ## Table of Contents - [Overview](#overview) - [Main Features](#main-features) - [Meridian Project Ecosystem](#meridian-project-ecosystem) - [Usage](#usage) - [Prerequisites](#prerequisites) - [Installing required packages](#installing-required-packages) - [Startup](#startup) - [Shutdown](#shutdown) - [Quick Start](#quick-start) - [Quick Start 1: Reset the state](#quick-start-1-reset-the-state) - [Quick Start 2: Adjust the standing posture](#quick-start-2-adjust-the-standing-posture) - [Quick Start 3: Start and stop walking](#quick-start-3-start-and-stop-walking) - [Quick Start 4: Check the walking status](#quick-start-4-check-the-walking-status) - [Quick Start 5: Control the robot from AI chat via MCP server (Claude Desktop)](#quick-start-5-control-the-robot-from-ai-chat-via-mcp-server-claude-desktop) - [Quick Start 6: Control the robot from AI chat via MCP server (Claude Code)](#quick-start-6-control-the-robot-from-ai-chat-via-mcp-server-claude-code) - [Detailed Documentation](#detailed-documentation) --- ## Usage ### Prerequisites 1. Understand the overview of [Meridian](https://meridian-oss.github.io/#project). 2. Complete the setup of [meridis](https://github.com/holypong/meridis). 3. Complete the setup of [merimujoco](https://github.com/holypong/merimujoco). (Confirmed up to Quick Start 1-2) Launch `merimujoco.py` with the following options. ```python python merimujoco.py --redis redis-ai.json ``` ### Installing required packages After satisfying the [prerequisites](#prerequisites), install the following packages. ```bash pip install "gradio[mcp]>=5.29.0" redis numpy ``` ### Startup ```bash python mcp-meridis.py ``` The following logs are displayed at startup. ``` WalkParams loaded from walkparam.json LinkParams loaded from linkparam.json [Config] Loaded Redis configuration from 'redis.json' [Config] Redis: 127.0.0.1:6379 [Config] Redis Keys: Read='meridis_sim_pub', Write='meridis_ai_pub' Redis list 'meridis_ai_pub' already exists. [Info] Starting Gradio web interface... * Running on local URL: http://127.0.0.1:7860 🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse ``` After startup, open `http://localhost:7860` or `http://127.0.0.1:7860/` in your browser to display the Web UI.  The SSE access point `http://127.0.0.1:7860/gradio_api/mcp/sse` in the startup log is used when utilizing it as an MCP server. ### Shutdown Press CTRL+C on the terminal to shut down. --- ## Quick Start - If you want to operate the humanoid from the Web UI, try Quick Start 1-4. - If you want to operate the humanoid from AI chat, try Quick Start 5 or 6. --- ### Quick Start 1: Reset the state Pressing the [Sysreset] button resets the system state of `merimujoco`. For example, if the humanoid is lying on the floor or has deviated from the initial position and posture, it returns the humanoid to the state immediately after startup. --- ### Quick Start 2: Adjust the standing posture Switch the standing posture of the humanoid on `merimujoco` between the home position and idle position. Pressing the [Home] button results in a standing home position (left figure) with knees straightened. Pressing the [Idle] button results in a waiting posture (right figure) with slightly bent knees before walking.  --- ### Quick Start 3: Start and stop walking Pressing the [Walk] button starts the humanoid walking on `merimujoco`, and it automatically stops after the time set in Duration. To stop quickly, press the [Stop] button. To start over, press the [Sysreset] button.  --- ### Quick Start 4: Check the walking status During walking or stopping, pressing the [Status] button repeatedly allows acquiring internal information about state transitions and posture.  --- ### Quick Start 5: Control the robot from AI chat via MCP server (Claude Desktop) `mcp-meridis` works as an MCP server. Here, we briefly explain how to set up the MCP server in `Claude Desktop`. For details, see the official website `https://claude.com`. ### 1) Install Claude Desktop Install and launch Claude Desktop. https://claude.com/download ### 2) Install Node.js Node.js is required to use `mcp-remote`. If not installed, download it from [nodejs.org](https://nodejs.org/). ### 3) Launch mcp-meridis Run the following in another terminal. ```bash python mcp-meridis.py ``` Confirm that the following appears in the startup log. ```text 🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse ``` ### 4) Add MCP settings to Claude Desktop 1. Launch Claude Desktop. 2. Open **"File" → "Settings"** (on macOS, **"Claude" → "Settings..."**).  3. Select **"Developer"** from the left menu.  4. Click **"Edit settings"** and open `claude_desktop_config.json`. 5. Add and save the following: ```json { "mcpServers": { "mcp-meridis": { "command": "npx", "args": [ "mcp-remote", "http://127.0.0.1:7860/gradio_api/mcp/sse" ] } } } ``` 6. Close with **"File" → "Exit"**. 7. **Restart** Claude Desktop. 8. Open **"File" → "Settings"** (on macOS, **"Claude" → "Settings..."**).  9. Select **"Developer"** from the left menu. At this point, if `mcp-meridis` is `running`, it's a success.  ### 5) Control the robot with AI chat Enter the following prompt.  **If the [Allow always] button appears, press it** The robot's status is displayed.  When instructed to "Make the robot walk," if the humanoid on `merimujoco` reacts, it's a success.  ### Basic prompt examples | Prompt example | Expected effect | |---|---| | Tell me the robot's status | Display the robot's status | | Make the robot walk | Start walking (default 5 seconds) | | Make it walk for 3 seconds | Walk for 3 seconds and then automatically stop | | Stop the robot | Stop safely via on-the-spot stepping | | Take the idle position | Transition to the standing posture right before walking | | Take the home position | Transition all joints to the zero position (home posture) | | Check the robot's status | Display walking status, time, IMU, fall judgment, etc. | | Send a system reset | Send a reset signal to initialize the system | ### Troubleshooting When the MCP server cannot connect: - Confirm if Claude Desktop is installed. - Confirm if Node.js is installed. - Before launching AI chat `Claude Desktop`, confirm that `python mcp-meridis.py` is running. - Check if the MCP server startup log and the SSE endpoint described in `claude_desktop_config.json` match `http://127.0.0.1:7860/gradio_api/mcp/sse`. - Check the JSON syntax (commas and braces) of `claude_desktop_config.json`. --- ### Quick Start 6: Control the robot from AI chat via MCP server (Claude Code) This section explains the case where the AI chat is changed from `Claude Desktop` to `Claude Code`. ### 1) Install Claude Code Install and launch Claude Code. https://code.claude.com/docs/ja/quickstart ### 2) Launch mcp-meridis Run the following in another terminal. ```bash python mcp-meridis.py ``` Confirm that the following appears in the startup log. ```text 🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse ``` ### 3) Add MCP settings to Claude Code Run the following in the terminal where Claude Code is launched. ```bash claude mcp add --transport sse mcp-meridis http://127.0.0.1:7860/gradio_api/mcp/sse ```  After addition, you can check the connection status with the `/mcp` command. If it's `connected`, it's a success.  **If you have trouble with the setup, ask Claude Code as follows:** > ``` > Please register the MCP server of mcp-meridis at http://127.0.0.1:7860/gradio_api/mcp/sse as an SSE connection. > ``` ### 4) Control the robot with AI chat Enter prompts in the chat similar to Quick Start 5. If the humanoid on `merimujoco` reacts, it's a success. --- ## Detailed Documentation [Read technical specifications](README_advance.md) summarizes: - Startup options and connection settings (simulation/real machine) - Web UI tab operation guide - MCP tool list and practical prompt examples - Log collection, visualization, and analysis tool usage - File configuration and major parameter reference [Background, purpose, and glossary](https://github.com/holypong/meridis/blob/main/README_concept.md) - Background based on meridian - Purpose of making it an MCP server - Glossary of physical AI, embodied AI, etc. ## License This project is licensed under the MIT License - see the LICENSE file for details.