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, luôn cài mcp 1.xcònFastMCP`.
• 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).

---

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    vn-sketchup-mcp (Python)    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 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 `` = đường dẫn tuyệt đối bạn đã clone):

{
  "mcpServers": {
    "sketchup": {
      "command": "uv",
      "args": ["run", "--directory", "", "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  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\\\\.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.