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
-
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
-
MCP Server (
mcp_server/)- FastAPI-based REST server
- Routes requests to appropriate LLM
- Validates and normalizes responses
- Caches conversation history
-
LLM Clients (
mcp_server/llm_clients/)- Unified interface for all models
- Provider-specific implementations
- Automatic retry and error handling
-
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
-
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/
- Windows:
-
Rename to
FusionMCP:cp -r fusion_addin "/Users/YOUR_USER/Library/Application Support/Autodesk/Autodesk Fusion 360/API/AddIns/FusionMCP" -
Restart Fusion 360
-
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
- Open Fusion 360
- Click Scripts and Add-Ins → Add-Ins → FusionMCP → Run
- Click MCP Assistant button in toolbar
- 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
- Creative Design: OpenAI GPT-4o → Claude (validation)
- Geometric Precision: Gemini → OpenAI
- Privacy-First: Ollama (all tasks)
- 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
- 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
}
- 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.manifestexists - 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=Truein 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:
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - 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
- 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