vn-sketchup-mcp

Điều khiển SketchUp từ Claude Code / Codex / Antigravity (và mọi MCP client dùng stdio) thông qua Model Context Protocol.

Bản Việt hoá + đã vá lỗi của mhyrr/sketchup-mcp: cài phát chạy ngay, không còn crash do lệch phiên bản thư viện mcp.

Control SketchUp from Claude Code / Codex / Antigravity via MCP. A fixed, ready-to-run fork of mhyrr/sketchup-mcp.

Vá gì so với bản gốc? (What is fixed)

Bản gốc crash ngay khi khởi động server vì:

1. Nó import mcp.server.fastmcp (lớp FastMCP). Nhưng thư viện mcp bản 2.x đã đổi tên FastMCP -> MCPServer, xoá mcp.server.fastmcp. Khi cài bằng uvx/pip không ghim phiên bản, máy kéo về mcp 2.x -> ModuleNotFoundError / crash -> MCP client báo Connection closed.

2. Gói trên PyPI còn dùng API cũ FastMCP(description=...) (đã bỏ), lỗi unexpected keyword argument 'description'.

Cách vá ở repo này:

• pyproject.toml ghim mcp[cli]>=1.3,<2 -> luôn cài mcp 1.x còn FastMCP.

• Dùng server.py bản mới (đã đổi sang FastMCP(instructions=...), hợp lệ với mcp 1.x).

• Kèm installer 1 lệnh tự copy plugin Ruby vào mọi bản SketchUp + in sẵn cấu hình cho 3 client.

Kết quả: uv run vn-sketchup-mcp chạy ổn, kết nối được SketchUp (đã kiểm chứng trên SketchUp Pro 2018, Ruby 2.2.4; và các bản mới hơn).

Related MCP server: CDT-SketchUp

Kiến trúc (How it works)

Gồm 2 phần:

1. Plugin SketchUp (Ruby) — chạy 1 TCP server bên trong SketchUp ở cổng 9876, nhận lệnh và thao tác model.

2. MCP server (Python) — client (Claude Code/Codex/Antigravity) chạy qua stdio; nó nối tới cổng 9876 để đẩy lệnh vào SketchUp.

Claude Code / Codex / Antigravity  <--stdio-->  vn-sketchup-mcp (Python)  <--TCP:9876-->  SketchUp (Ruby plugin)

Yêu cầu

• uv (tự tải Python 3.12, không cần cài Python riêng)

• git

• SketchUp (Pro để dùng được đủ Solid Tools; đã test 2018+)

Cài đặt (Install)

1. Clone

git clone https://github.com/andyluu98/vn-sketchup-mcp.git
cd vn-sketchup-mcp

2. Chạy installer (khuyên dùng)

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File install.ps1

macOS / Linux:

bash install.sh

Installer sẽ: cài uv nếu thiếu -> uv sync (ghim mcp<2) -> copy plugin Ruby vào mọi bản SketchUp phát hiện được -> in sẵn cấu hình MCP.

3. Bật server trong SketchUp

Mở SketchUp -> menu Extensions > MCP Server > Start Server. Ruby Console hiện Server created on port 9876 là OK. Giữ SketchUp mở khi dùng.

Đăng ký MCP cho từng client

Cấu hình cùng một dạng cho cả 3 (thay <REPO> = đường dẫn tuyệt đối bạn đã clone):

{
  "mcpServers": {
    "sketchup": {
      "command": "uv",
      "args": ["run", "--directory", "<REPO>", "vn-sketchup-mcp"]
    }
  }
}

• Claude Code: thêm vào ~/.claude.json (mục mcpServers) hoặc chạy:

  claude mcp add sketchup -- uv run --directory <REPO> vn-sketchup-mcp

• Codex: thêm MCP server dạng trên vào cấu hình Codex (~/.codex/config.toml phần [mcp_servers] hoặc file cấu hình MCP tương ứng).

• Antigravity: thêm cùng khối mcpServers vào phần cấu hình MCP của Antigravity.

Sau khi thêm, khởi động lại client. Nhớ SketchUp đang mở + đã Start Server.

Nếu uv không nằm trong PATH của client, thay "command": "uv" bằng đường dẫn tuyệt đối tới uv (vd C:\\Users\\<ban>\\.local\\bin\\uv.exe).

Công cụ (MCP tools)

eval_ruby là công cụ linh hoạt nhất: bạn mô tả, agent sinh Ruby dựng nhà/nội thất trực tiếp trong SketchUp.

Xử lý sự cố (Troubleshooting)

Ghi công (Credits)

• Fork từ mhyrr/sketchup-mcp (MIT).

• Việt hoá, vá lỗi phiên bản mcp, thêm installer đa client: andyluu98.

MIT License.