🚀 SketchupMCP - Sketchup Model Context Protocol (MCP) Integration

SketchupMCP connects Sketchup to Claude AI through the Model Context Protocol (MCP), enabling Claude to directly interact with and control Sketchup. This integration allows for prompt-assisted 3D modeling, scene creation, and Sketchup operations.

Special thanks to mhyrr/sketchup-mcp for providing the architecture. We have translated the original version (mhyrr/sketchup-mcp) into Traditional Chinese and optimized and adjusted some of its functions.

🚀 Quick Start

SketchupMCP connects Sketchup to Claude AI via the Model Context Protocol (MCP), enabling Claude to interact with and control Sketchup directly. This integration supports prompt-assisted 3D modeling, scene creation, and Sketchup operations.

✨ Features

• Bidirectional Communication: Connects Claude AI to Sketchup via TCP sockets.
• Component Operations: Creates, modifies, deletes, and transforms components in Sketchup.
• Material Control: Applies and modifies materials and colors.
• Scene Inspection: Retrieves detailed information about the current Sketchup scene.
• Selection Handling: Retrieves and manipulates selected components.
• Ruby Code Execution: Performs complex modeling operations using the Ruby language.

🔧 Technical Details

System Structure Overview

The SketchupMCP system consists of the following main components:

1. Sketchup Extension

   • Function: Serves as a communication bridge between the Sketchup platform and external servers.
   • Role: Receives user commands, sends them to the server via TCP sockets, and relays server responses back to the client.

2. MCP Server

   • Function: Handles requests from the Sketchup extension and executes corresponding operations.
   • Role: Parses commands, performs modeling or operations, and feeds the results back to the client.

Specific Structure

• Sketchup Extension

  • Installation Steps:
    1. Download and install Sketchup.
    2. After launching the software, install the SketchupMCP plugin from the extension library.
    3. After opening the plugin, connect to the MCP server as prompted.

• MCP Server

  • Installation Steps:
    1. Install a Python environment (it is recommended to use the latest version).
    2. Clone the SketchupMCP project repository using Git.
    3. After starting the server, configure the IP and ports for client connections.

📦 Installation

Sketchup Extension Installation

1. Download and Install Sketchup

   • Download from the official website: Sketchup Official Website

2. Launch the Software and Install the Extension

   • Open Sketchup.
   • Navigate to the "Edit" menu and select "Extension Library".
   • Find and install the SketchupMCP extension among the available extensions.

3. Enable the Plugin

   • After installation, locate the SketchupMCP icon in the toolbar.
   • Click the icon to start the plugin and connect to the MCP server as prompted.

Python Package Installation

1. Install a Python Environment

   • It is recommended to use Anaconda or Pyenv to manage multiple versions of the environment.

2. Install Dependencies

   • Open a terminal and run the following command:

pip install sketchupmcp

3. Start the Server
   • Start the MCP server using the following command:

python -m sketchupmcp.server --host <IP> --port <PORT>

- Adjust `<IP>` and `<PORT>` to ensure proper connection with the Sketchup extension.

💻 Usage Examples

Connection Setup

1. Start the Server
   • Run the following command in the terminal:

python -m sketchupmcp.server --host localhost --port 8000

2. Enable the Extension and Connect
   • Open Sketchup.
   • Enable the SketchupMCP plugin and select the server IP and ports to connect to the server.

Operation Commands

• Basic Commands

{
    "type": "create_house",
    "params": {
        "roof_type": "gabled",
        "window_count": 4
    }
}

• Selection Operations

{
    "type": "select_components"
}

• Color Modification

{
    "type": "change_color",
    "params": {
        "color": "#FF0000"
    }
}

🛠️ Troubleshooting

Connection Issues

1. Server Not Started

   • Check if the server has been started correctly and is displaying a standby message.

2. Firewall Interference

   • Ensure that the server's firewall allows TCP ports for connections.

3. Network Issues

   • Use the ping command to test the network connectivity between the server and the client.

Operation Failures

1. Check Error Messages

   • Check the Sketchup Ruby console to capture and analyze error messages.

2. Restart the Services

   • Sometimes, simply restarting the server and the client can resolve transient issues.

Advanced Debugging

• Logging

python -m sketchupmcp.server --log-level DEBUG

• Error Backtracking
  • Ensure that all third-party libraries are updated to the latest version to avoid potential compatibility issues.

🔒 Security Considerations

Authentication Mechanisms

1. User Authentication

   • Implement token-based authentication to ensure that only authorized users can connect to the server.

2. Data Encryption

   • Use SSL/TLS to encrypt the communication channel and prevent sensitive data from being intercepted.

Common Attack Prevention

1. DDoS Attack Prevention

   • Configure rate-limiting policies to limit the number of concurrent connections.

2. Injection Attack Protection

   • Perform thorough input filtering and validation when processing external commands.

❓ Frequently Asked Questions

Q1: How do I install the SketchupMCP plugin?

A: Follow these steps:

1. Open Sketchup.
2. Navigate to "Edit" > "Extension Library".
3. Install the SketchupMCP plugin.

Q2: What should I do if the server fails to start?

A:

1. Ensure that you have installed the latest version of Python and all dependencies.
2. Check if any other programs are using the same ports.
3. Review the server startup logs for error messages.

Q3: How do I change the server port number?

A: Specify the new port in the startup command:

python -m sketchupmcp.server --host localhost --port 8001

Q4: What could be the reasons for the plugin failing to connect to the server?

A:

1. The server may not be started correctly.
2. Ensure that the client and the server are on the same network.
3. Check if the ports are open.

Q5: How do I protect the server from unauthorized access?

A:

1. Enable user authentication.
2. Use SSL encryption for connections.
3. Regularly update the software to patch security vulnerabilities.

📊 Common Errors and Solutions

🌟 Advanced Topics

Cluster Architecture

1. Load Balancing

   • Use Nginx or HAProxy to distribute requests across multiple servers.

2. Auto-Scaling

   • Configure an elastic cloud service to automatically adjust the number of instances based on the load.

3. Session Management

   • Use middleware such as Redis to manage and synchronize client session states.

Performance Optimization

1. Opcode Caching

   • Use opcode caches like Redis or Memcached to speed up repetitive operations.

2. Parallel Processing

   • Utilize multi-threading or multi-processing models to enhance the server's processing capabilities.

3. Database Optimization

   • Ensure that database indexes are optimized to avoid full-table scans.

Security Hardening

1. Principle of Least Privilege

   • Grant each account only the minimum level of privileges required to perform its tasks.

2. Regular Security Audits

   • Conduct regular security audits to identify and mitigate vulnerabilities.

3. Intrusion Detection System

   • Deploy an IDS/IPS system to monitor and block suspicious activities.

⚙️ Advanced Configuration

Authentication Methods

1. JWT Authentication

   • Use JSON Web Tokens for lightweight user authentication.

2. OAuth2 Integration

   • Integrate the server with third-party authorization services (e.g., Google, Facebook) to provide federated login functionality.

Log Management

1. Log Data Storage

   • Use a professional logging library such as the ELK Stack (Elasticsearch, Logstash, Kibana) for log collection, processing, and visualization.

2. Log Dashboard

   • Configure a log dashboard to monitor the server's running status in real-time and quickly identify issues.

Monitoring and Alerts

1. Performance Monitoring

   • Use Prometheus + Grafana to monitor server performance metrics.

2. Anomaly Detection

   • Configure a machine learning-based anomaly detection system to detect unusual traffic patterns.

3. Instant Notifications

   • Ensure that you receive instant notifications via multiple communication channels (e.g., email, SMS) when issues occur.

📚 Common Error Codes

📝 Conclusion

SketchupMCP is a powerful plugin that helps you achieve various complex architectural designs and simulations in SketchUp. Through proper configuration and best practices, you can fully leverage its potential and improve work efficiency. We hope this guide will assist you, and wish you a smooth modeling process!

Appendices:

• Appendix A: Installing Dependencies
• Appendix B: Authentication Mechanisms
• Appendix C: Common Commands and Scripts

References:

1. SketchUp official documentation
2. Relevant technical whitepapers
3. Internal records of the development team

Note: This guide is for demonstration purposes, and the specific content may vary depending on the version. It is recommended to refer to the latest official documentation when using the plugin.

SketchupMCP Plugin User Manual

SketchupMCP is a powerful plugin that helps you achieve various complex architectural designs and simulations in SketchUp. This guide aims to provide you with comprehensive configuration and usage recommendations to fully leverage its potential.

📑 Table of Contents

1. Installation and Configuration

   • 1.1 Installation Steps
   • 1.2 Environmental Dependencies
   • 1.3 Initial Setup

2. Basic Usage

   • 2.1 Plugin Function Overview
   • 2.2 Shortcuts and Operation Guide
   • 2.3 Common Commands Reference

3. Advanced Configuration

   • 3.1 Cluster Architecture
   • 3.2 Load Balancing Setup
   • 3.3 Security Hardening Measures

4. Error Troubleshooting and Solutions

   • 4.1 Common Error Codes
   • 4.2 Error Diagnosis Steps
   • 4.3 Log Analysis Methods

5. Appendices

   • 5.1 Installing Dependencies
   • 5.2 Detailed Introduction to Authentication Mechanisms
   • 5.3 Examples of Common Commands and Scripts

📦 Installation and Configuration

1.1 Installation Steps

1. Download the latest version of the SketchupMCP plugin.
2. Open SketchUp, check for available updates, and install the plugin.
3. Launch SketchUp, navigate to Edit > Extension Library to confirm that the plugin is installed correctly.

1.2 Environmental Dependencies

• Operating System: Windows 7 or later, MacOS X 10.10 or later.
• SketchUp Version: Supports SketchUp 2018 or later.
• Python Environment: Ensure that Python 3.6 or a higher version is installed.

1.3 Initial Setup

1. Open SketchUp, navigate to Edit > Extension Library.
2. Select the SketchupMCP plugin and open it.
3. Complete the initial setup according to the wizard, including selecting the working directory and configuring basic options.

🛠️ Basic Usage

2.1 Plugin Function Overview

SketchupMCP offers various functional modules, including architectural modeling, structural analysis, and energy consumption calculation, making it suitable for professional architects and designers.

2.2 Shortcuts and Operation Guide

• Button: Locate the SketchupMCP button in the SketchUp toolbar and click it to start the plugin.
• Shortcuts: Set up custom shortcuts to improve work efficiency.

2.3 Common Commands Reference

# Example commands
mcp new_project [project_name]  # Create a new project
mcp open [project_path]         # Open an existing project
mcp save                        # Save the current project

⚙️ Advanced Configuration

3.1 Cluster Architecture

• Configure Multiple Servers: Set up a cluster mode in SketchupMCP to distribute the computational load.
• Communication Protocol: Choose an appropriate communication protocol (e.g., HTTP/HTTPS) to ensure secure data transmission.

3.2 Load Balancing Setup

• Configure a Reverse Proxy: Use server software such as Nginx or Apache to implement load balancing.
• Health Check Mechanism: Configure a health check mechanism to ensure that each server is in a normal state.

3.3 Security Hardening Measures

• SSL Certificates: Use SSL encryption for communication to protect data security.
• Authentication and Authorization: Configure multi-level user permission management to restrict unauthorized access.

🚑 Error Troubleshooting and Solutions

4.1 Common Error Codes

4.2 Error Diagnosis Steps

1. Check the log files for error codes.
2. Make corresponding configuration adjustments based on the causes associated with the error codes.

4.3 Log Analysis Methods

• Log Dashboard: Use tools such as Grafana to visualize log data and quickly identify issues.

📚 Appendices

5.1 Installing Dependencies

pip install -r requirements.txt

5.2 Detailed Introduction to Authentication Mechanisms

• Basic Authentication: Use the $username:$password format for authentication.
• Token-Based Authentication: Use tokens to enhance security.

5.3 Examples of Common Commands and Scripts

# Example script
#!/bin/bash
mcp batch_process /path/to/projects/

📝 Conclusion

SketchupMCP is a powerful plugin that helps you achieve various complex architectural designs and simulations in SketchUp. Through proper configuration and best practices, you can fully leverage its potential and improve work efficiency. We hope this guide will assist you, and wish you a smooth modeling process!

Appendices:

• Appendix A: Installing Dependencies
• Appendix B: Authentication Mechanisms
• Appendix C: Common Commands and Scripts

References:

1. SketchUp official documentation
2. Relevant technical whitepapers
3. Internal records of the development team

Note: This guide is for demonstration purposes, and the specific content may vary depending on the version. It is recommended to refer to the latest official documentation when using the plugin.