Skip to content

mcp.md

Latest commit

 

History

History
259 lines (197 loc) · 5.32 KB

mcp.md

File metadata and controls

259 lines (197 loc) · 5.32 KB

MCP Server

The Rhino CLI includes a Model Context Protocol (MCP) server that allows Claude Desktop and other MCP clients to control Rhino 3D.

Overview

The MCP server uses stdio transport with JSON-RPC 2.0 protocol to communicate with MCP clients like Claude Desktop. It connects to the existing Rhino HTTP server (localhost:9090) and provides access to Rhino functionality through MCP tools and resources.

Architecture

Claude Desktop
  ↓ (spawns process)
rhino mcp (stdio JSON-RPC)
  ↓ (HTTP requests)
rhino server (localhost:9090)
  ↓ (queue + proxy)
Rhino Python Server (TCP 17890)

Starting the MCP Server

# Terminal 1: Start HTTP server
rhino server

# Terminal 2: Start MCP server
rhino mcp

The MCP server requires the HTTP server to be running first.

MCP Tools

The server exposes five tools that Claude can call:

1. rhino_exec

Execute Python code in Rhino.

Input:

  • code (string, required): Python code to execute

Output:

  • Execution result (stdout, stderr, result)

Example:

{
  "name": "rhino_exec",
  "arguments": {
    "code": "rs.AddPoint([0,0,0]); sc.doc.Views.Redraw()"
  }
}

2. rhino_eval

Evaluate a Python expression and return its value.

Input:

  • expr (string, required): Python expression to evaluate

Output:

  • Value of the expression

Example:

{
  "name": "rhino_eval",
  "arguments": {
    "expr": "rs.UnitSystem()"
  }
}

3. rhino_status

Get the current status of the Rhino server.

Input: None

Output:

  • Server status (version, python version, mode, etc.)

4. rhino_render_viewport

Render the current Rhino viewport as a PNG image.

Input:

  • width (number, optional): Image width in pixels (default: 800)
  • height (number, optional): Image height in pixels (default: 600)

Output:

  • Base64-encoded PNG image

Example:

{
  "name": "rhino_render_viewport",
  "arguments": {
    "width": 1024,
    "height": 768
  }
}

5. rhino_introspect

Introspect available Rhino APIs.

Input:

  • api (string, required): API to introspect: "rs" (rhinoscriptsyntax) or "rhino" (RhinoCommon)

Output:

  • List of available functions/types

Example:

{
  "name": "rhino_introspect",
  "arguments": {
    "api": "rs"
  }
}

MCP Resources

The server exposes three resources that Claude can read:

1. rhino://viewport

Current viewport screenshot as PNG image.

MIME Type: image/png

Description: Always returns the current state of the Rhino viewport

2. rhino://objects

List of all objects in the current Rhino document.

MIME Type: application/json

Description: Returns a JSON array of object GUIDs

3. rhino://status

Current status of the Rhino server.

MIME Type: application/json

Description: Server health, version, and configuration info

Protocol Details

Transport

  • Type: stdio (standard input/output)
  • Format: Newline-delimited JSON-RPC 2.0 messages
  • Logging: All logs go to stderr, stdout is reserved for JSON-RPC

Message Format

All messages follow JSON-RPC 2.0 specification:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "rhino_exec",
    "arguments": {
      "code": "print('hello')"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "hello\n"
      }
    ],
    "isError": false
  }
}

Capabilities

The server announces these capabilities during initialization:

{
  "capabilities": {
    "tools": {},
    "resources": {}
  }
}

Configuration

See Claude Desktop Setup for configuration instructions.

Error Handling

The MCP server returns standard JSON-RPC error codes:

  • -32601: Method not found
  • -32602: Invalid params (unknown tool/resource)
  • -32603: Internal error (execution failed)

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "unknown tool: invalid_tool"
  }
}

Limitations

  • Single HTTP server: Can only connect to one Rhino HTTP server at a time
  • No streaming: All responses are complete (no streaming support yet)
  • No prompts: MCP prompts are not implemented yet
  • Synchronous: All operations are synchronous (no async/await)

Troubleshooting

MCP server won't start

  1. Ensure HTTP server is running: rhino server
  2. Check that port 9090 is accessible: rhino ping
  3. Check stderr for error messages

Claude Desktop not connecting

  1. Verify config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
  2. Check config JSON syntax
  3. Verify command path points to your rhino binary
  4. Restart Claude Desktop after config changes

Tools not working

  1. Verify HTTP server is healthy: curl http://localhost:9090/healthz
  2. Check that Rhino process is running
  3. Look for errors in MCP server logs (stderr)
  4. Test tools directly via HTTP: rhino exec --code "print('test')"

Future Enhancements

  • Add MCP prompts for common workflows
  • Support streaming responses for long-running operations
  • Add more resources (layers, materials, views)
  • Support connecting to remote HTTP servers
  • Add authentication/authorization
  • Implement progress notifications