Georges999/MeshLab-mcp

MeshLab-MCP

A minimal, extensible Model Context Protocol (MCP) bridge for MeshLab, using FastAPI (HTTP) and a custom TCP (JSON) backend for mesh operations via pymeshlab.

Features

• HTTP API for MCP clients (web UIs, orchestrators) using FastAPI
• TCP (JSON) backend to communicate with a MeshLab process (using pymeshlab)
• Extensible: Add new mesh tools and protocol commands easily

Project Structure

MeshLab-mcp/
├── meshlab_tcp_server.py   # TCP server wrapping pymeshlab
├── meshlab_tcp_client.py   # TCP client for server communication
├── meshlab_mcp.py          # Core MCP protocol logic (extensible)
├── mcp_server.py           # FastAPI HTTP server (entrypoint)
├── mcp_client.py           # HTTP client for testing
├── requirements.txt
└── README.md

Setup Instructions

1. Clone the repository and cd into the directory.

2. Install dependencies:

   pip install -r requirements.txt
   

3. Add Python Scripts directory to PATH (if not already):

   • Example: C:\Users\<your-username>\AppData\Roaming\Python\Python313\Scripts\
   • Restart your terminal after changing PATH.

4. Start the MeshLab TCP server (in a terminal):

   python meshlab_tcp_server.py
   

5. Start the HTTP MCP server (in another terminal):

   python -m uvicorn mcp_server:app --reload
   

   If uvicorn is not recognized, use the full path or the python -m uvicorn ... form as above.

6. Test with the HTTP client (optional):

   python mcp_client.py
   

   You should see output like:

   {'mesh_loaded': False, 'current_mesh_name': None}
   

MCP Client Configuration Example (for MeshLab integration)

To connect MeshLab (or an orchestrator) to this MCP server, use a configuration like:

{
  "mcpServers": {
    "meshlab": {
      "command": "uvx",
      "args": [
        "meshlab-mcp"
      ],
      "host": "127.0.0.1",
      "port": 8000
    }
  }
}

• command: The command to launch your MCP HTTP server (e.g., uvx meshlab-mcp or python -m uvicorn mcp_server:app --reload)
• host/port: Where the HTTP API is reachable.

How It Works

• MCP clients (web UI, orchestrator) send HTTP requests to the FastAPI server.
• The FastAPI server bridges these requests to the MeshLab TCP server (which runs mesh operations using pymeshlab).
• The TCP server responds with JSON results.

Extending

• Add new mesh tools/commands in meshlab_tcp_server.py and expose them in the protocol.
• Add corresponding methods in meshlab_tcp_client.py and new HTTP endpoints in mcp_server.py.

Troubleshooting

• If uvicorn is not recognized, ensure your Python Scripts directory is in PATH or use python -m uvicorn ....
• Always start the TCP server before the HTTP server.
• For mesh operations, ensure your mesh files are present in the working directory.

Next Steps

• Start building new mesh tools and protocol commands!
• For advanced integration with MeshLab's GUI or other tools, refer to MeshLab's documentation and MCP specs.

If you have questions or want to add new features, just ask!