Fusion 360 MCP - Multi-Model AI Integration

FusionMCP is a comprehensive Model Context Protocol (MCP) integration layer that connects Autodesk Fusion 360 with multiple AI backends (Ollama, OpenAI, Google Gemini, and Anthropic Claude) to enable AI-powered parametric CAD design through natural language.

🎯 Features

• 🤖 Multi-Model Support: Seamlessly switch between Ollama, OpenAI GPT-4o, Google Gemini, and Claude 3.5
• 🔄 Intelligent Routing: Automatic fallback chain when primary model fails
• 📐 Parametric Design: AI understands and generates parametric CAD operations
• 🛡️ Safety First: Built-in validation for dimensions, units, and geometric feasibility
• 💾 Context Caching: Conversation and design state persistence (JSON/SQLite)
• 🎨 Fusion 360 Integration: Native add-in for seamless workflow
• ⚡ Async Architecture: Fast, non-blocking operations with retry logic
• 📊 Structured Logging: Detailed logs with Loguru

📋 Table of Contents

• Architecture
• Installation
• Quick Start
• Configuration
• Usage Examples
• API Reference
• Model Comparison
• Development
• Troubleshooting
• Contributing

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Fusion 360 User                         │
│                           ↓                                 │
│              ┌─────────────────────────┐                    │
│              │  Fusion 360 Add-in      │                    │
│              │  - UI Dialog            │                    │
│              │  - Action Executor      │                    │
│              │  - Network Client       │                    │
│              └──────────┬──────────────┘                    │
│                         ↓ HTTP/REST                         │
│              ┌─────────────────────────┐                    │
│              │   MCP Server (FastAPI)  │                    │
│              │  - Router               │                    │
│              │  - Schema Validation    │                    │
│              │  - Context Cache        │                    │
│              └──────────┬──────────────┘                    │
│                         ↓                                    │
│         ┌───────────────┴───────────────────┐               │
│         ↓               ↓           ↓       ↓               │
│   ┌─────────┐   ┌──────────┐  ┌────────┐  ┌──────────┐     │
│   │ Ollama  │   │  OpenAI  │  │ Gemini │  │  Claude  │     │
│   │ (Local) │   │   API    │  │  API   │  │   API    │     │
│   └─────────┘   └──────────┘  └────────┘  └──────────┘     │
│                                                              │
│              System Prompt (FusionMCP Personality)          │
│              ↓                                              │
│         Structured JSON Actions → Fusion 360                │
└─────────────────────────────────────────────────────────────┘

Component Overview

1. Fusion 360 Add-in (fusion_addin/)

   • Python-based Fusion 360 add-in
   • Captures user intent and design context
   • Executes structured CAD actions
   • Real-time UI feedback

2. MCP Server (mcp_server/)

   • FastAPI-based REST server
   • Routes requests to appropriate LLM
   • Validates and normalizes responses
   • Caches conversation history

3. LLM Clients (mcp_server/llm_clients/)

   • Unified interface for all models
   • Provider-specific implementations
   • Automatic retry and error handling

4. System Prompt (prompts/system_prompt.md)

   • Defines FusionMCP personality
   • Enforces JSON output format
   • Provides action schema templates

🚀 Installation

Prerequisites

• Python 3.11+ (for MCP server)
• Autodesk Fusion 360 (2025 version recommended)
• At least one LLM provider:
  • Ollama (local, free)
  • OpenAI API Key
  • Google AI API Key
  • Anthropic API Key

Step 1: Clone Repository

git clone https://github.com/yourusername/fusion360-mcp.git
cd fusion360-mcp

Step 2: Install Python Dependencies

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

Step 3: Configure Environment

Create config.json from example:

cp examples/example_config.json config.json

Edit config.json with your API keys:

{
  "ollama_url": "http://localhost:11434",
  "openai_api_key": "sk-proj-...",
  "gemini_api_key": "AIza...",
  "claude_api_key": "sk-ant-...",
  "default_model": "openai:gpt-4o-mini",
  "mcp_host": "127.0.0.1",
  "mcp_port": 9000
}

Alternative: Use environment variables (.env file):

OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIza...
CLAUDE_API_KEY=sk-ant-...

Step 4: Install Fusion 360 Add-in

1. Copy fusion_addin/ folder to Fusion 360 add-ins directory:

   • Windows: %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\
   • macOS: ~/Library/Application Support/Autodesk/Autodesk Fusion 360/API/AddIns/

2. Rename to FusionMCP:

   cp -r fusion_addin "/Users/YOUR_USER/Library/Application Support/Autodesk/Autodesk Fusion 360/API/AddIns/FusionMCP"
   

3. Restart Fusion 360

4. Open Fusion 360 → Scripts and Add-Ins → Add-Ins tab → Select FusionMCP → Run

🎬 Quick Start

1. Start MCP Server

# Activate virtual environment
source venv/bin/activate

# Start server
python -m mcp_server.server

Expected output:

INFO     | Logger initialized with level INFO
INFO     | Cache initialized: json
INFO     | System prompt loaded
INFO     | Initialized MCP Router with providers: ['ollama', 'openai', 'gemini', 'claude']
INFO     | MCP Server started on 127.0.0.1:9000

2. Test Server (Optional)

curl -X POST http://127.0.0.1:9000/mcp/command \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ask_model",
    "params": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "prompt": "Create a 20mm cube"
    },
    "context": {
      "active_component": "RootComponent",
      "units": "mm",
      "design_state": "empty"
    }
  }'

3. Use in Fusion 360

1. Open Fusion 360
2. Click Scripts and Add-Ins → Add-Ins → FusionMCP → Run
3. Click MCP Assistant button in toolbar
4. Enter natural language command:
   • "Create a 20mm cube"
   • "Design a mounting bracket with 4 holes"
   • "Make a cylindrical shaft 10mm diameter, 50mm long"

⚙️ Configuration

Full Configuration Options

{
  // API Configuration
  "ollama_url": "http://localhost:11434",
  "openai_api_key": "sk-proj-...",
  "gemini_api_key": "AIza...",
  "claude_api_key": "sk-ant-...",

  // Model Selection
  "default_model": "openai:gpt-4o-mini",
  "fallback_chain": [
    "openai:gpt-4o-mini",
    "gemini:gemini-1.5-flash-latest",
    "ollama:llama3"
  ],

  // Server Settings
  "mcp_host": "127.0.0.1",
  "mcp_port": 9000,
  "allow_remote": false,

  // Logging
  "log_level": "INFO",
  "log_dir": "logs",

  // Caching
  "cache_enabled": true,
  "cache_type": "json",  // or "sqlite"
  "cache_path": "context_cache.json",

  // Timeouts and Retries
  "timeout_seconds": 30,
  "max_retries": 3,
  "retry_delay": 1.0,

  // Available Models
  "models": {
    "ollama": {
      "available": ["llama3", "mistral", "codellama"],
      "default": "llama3"
    },
    "openai": {
      "available": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
      "default": "gpt-4o-mini"
    },
    "gemini": {
      "available": ["gemini-1.5-pro-latest", "gemini-1.5-flash-latest"],
      "default": "gemini-1.5-flash-latest"
    },
    "claude": {
      "available": ["claude-3-5-sonnet-20241022"],
      "default": "claude-3-5-sonnet-20241022"
    }
  }
}

💡 Usage Examples

Example 1: Simple Geometry

Prompt: "Create a 20mm cube"

Generated Action:

{
  "action": "create_box",
  "params": {
    "width": 20,
    "height": 20,
    "depth": 20,
    "unit": "mm"
  },
  "explanation": "Creating a 20mm cubic box",
  "safety_checks": ["dimensions_positive", "units_valid"]
}

Example 2: Complex Design

Prompt: "Design a mounting bracket 100x50mm with 4 M5 mounting holes"

Generated Action Sequence:

{
  "actions": [
    {
      "action": "create_box",
      "params": {"width": 100, "height": 50, "depth": 5, "unit": "mm"},
      "explanation": "Create base plate"
    },
    {
      "action": "create_hole",
      "params": {"diameter": 5.5, "position": {"x": 10, "y": 10}, "unit": "mm"},
      "explanation": "M5 clearance hole (10mm edge offset)"
    },
    // ... 3 more holes
  ],
  "total_steps": 5
}

Example 3: Parametric Design

Prompt: "Create a shaft with diameter 2x of length"

{
  "clarifying_questions": [
    {
      "question": "What is the shaft length?",
      "context": "Need length to calculate diameter (diameter = 2 × length)",
      "suggestions": ["50mm", "100mm", "Custom"]
    }
  ]
}

📡 API Reference

Endpoints

POST /mcp/command

Execute MCP command.

Request Body:

{
  "command": "ask_model",
  "params": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "prompt": "User prompt here",
    "temperature": 0.7,
    "max_tokens": 2000
  },
  "context": {
    "active_component": "RootComponent",
    "units": "mm",
    "design_state": "empty"
  }
}

Response:

{
  "status": "success",
  "message": "Action generated successfully",
  "actions_to_execute": [...],
  "llm_response": {...}
}

GET /health

Health check.

Response:

{
  "status": "healthy",
  "providers": ["ollama", "openai", "gemini", "claude"],
  "cache_enabled": true
}

GET /models

List available models.

Response:

{
  "models": {
    "ollama": ["llama3", "mistral"],
    "openai": ["gpt-4o", "gpt-4o-mini"],
    "gemini": ["gemini-1.5-pro-latest"],
    "claude": ["claude-3-5-sonnet-20241022"]
  }
}

GET /history?limit=10

Get conversation history.

Response:

{
  "conversations": [...],
  "actions": [...]
}

Supported Actions

Action	Description	Required Params
create_box	Create rectangular box	width, height, depth, unit
create_cylinder	Create cylinder	radius, height, unit
create_sphere	Create sphere	radius, unit
create_hole	Create hole	diameter, position, unit
extrude	Extrude profile	profile, distance, unit
fillet	Round edges	edges, radius, unit
apply_material	Apply material	material_name

🔬 Model Comparison

Feature	Ollama (Local)	OpenAI GPT-4o	Google Gemini	Claude 3.5
Cost	Free	$$	$	$$$
Speed	Fast	Medium	Fast	Medium
Offline	✅ Yes	❌ No	❌ No	❌ No
JSON Mode	Limited	✅ Native	Good	Good
Reasoning	Good	Excellent	Very Good	Excellent
Geometry	Good	Very Good	Excellent	Very Good
Creative	Good	Excellent	Very Good	Good
Best For	Privacy, Offline	Creative designs	Spatial reasoning	Safety validation

Recommended Workflows

1. Creative Design: OpenAI GPT-4o → Claude (validation)
2. Geometric Precision: Gemini → OpenAI
3. Privacy-First: Ollama (all tasks)
4. Cost-Optimized: Gemini Flash → Ollama (fallback)

🛠️ Development

Project Structure

fusion360-mcp/
├── mcp_server/                 # MCP Server
│   ├── server.py              # FastAPI app
│   ├── router.py              # Request routing
│   ├── schema/                # Pydantic models
│   ├── llm_clients/           # LLM implementations
│   └── utils/                 # Utilities
├── fusion_addin/              # Fusion 360 Add-in
│   ├── main.py                # Entry point
│   ├── ui_dialog.py           # UI components
│   ├── fusion_actions.py      # Action executor
│   └── utils/network.py       # Network client
├── prompts/                   # System prompts
├── examples/                  # Example configs
├── tests/                     # Test suite
├── requirements.txt           # Dependencies
└── README.md                  # This file

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_mcp_server.py -v

# Run with coverage
pytest tests/ --cov=mcp_server --cov-report=html

Adding New LLM Provider

1. Create client in mcp_server/llm_clients/new_provider_client.py:

class NewProviderClient:
    async def generate(self, model, prompt, system_prompt, temperature, max_tokens):
        # Implementation
        return {
            "provider": "new_provider",
            "model": model,
            "output": "...",
            "json": {...},
            "tokens_used": 123
        }

2. Register in router.py:

if config.new_provider_api_key:
    self.clients["new_provider"] = NewProviderClient(...)

Code Style

• PEP8 compliant
• Type annotations required
• Docstrings for all functions/classes
• Async/await for I/O operations

🐛 Troubleshooting

Common Issues

1. Server Won't Start

Error: Address already in use

Solution: Change port in config.json:

{"mcp_port": 9001}

2. Fusion Add-in Not Visible

Solution:

• Verify add-in is in correct folder
• Check FusionMCP.manifest exists
• Restart Fusion 360
• Check Scripts and Add-Ins → Add-Ins tab

3. API Key Errors

Error: 401 Unauthorized

Solution:

• Verify API key in config.json
• Check key has proper permissions
• Try environment variables instead

4. Ollama Connection Failed

Error: Connection refused

Solution:

# Check Ollama is running
ollama list

# Start Ollama service
ollama serve

5. JSON Parsing Errors

Solution:

• Check system prompt is loaded
• Verify model supports JSON mode
• Use temperature < 0.8 for better structure
• Enable json_mode=True in OpenAI client

Debug Mode

Enable verbose logging:

{"log_level": "DEBUG"}

Check logs in logs/mcp_server.log

Health Check

# Check server health
curl http://127.0.0.1:9000/health

# List available models
curl http://127.0.0.1:9000/models

# View conversation history
curl http://127.0.0.1:9000/history?limit=5

🧪 Testing the System

Manual CLI Test

curl -X POST http://127.0.0.1:9000/mcp/command \
  -H "Content-Type: application/json" \
  -d @examples/example_command.json

Python Test Script

import requests

command = {
    "command": "ask_model",
    "params": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "prompt": "Create a 10mm cube"
    },
    "context": {
        "units": "mm",
        "design_state": "empty"
    }
}

response = requests.post("http://127.0.0.1:9000/mcp/command", json=command)
print(response.json())

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Development Setup

# Install dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run linting
ruff check mcp_server/
black mcp_server/

📄 License

MIT License - see LICENSE file

🙏 Acknowledgments

• Autodesk Fusion 360 API
• FastAPI framework
• Anthropic, OpenAI, Google for LLM APIs
• Ollama for local LLM support

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

🗺️ Roadmap

• [ ] WebSocket streaming for real-time chat
• [ ] Vision model support (CAD screenshot analysis)
• [ ] Multi-agent orchestration
• [ ] Generative Design API integration
• [ ] Geometry export to Markdown/docs
• [ ] Fusion 360 UI palette integration
• [ ] 3D preview before execution
• [ ] Undo/redo action history
• [ ] Cloud deployment support

---

Built with ❤️ for the Fusion 360 and AI community