8th Wall MCP Server

Build WebAR experiences with natural language using Claude Desktop and 8th Wall Desktop

🚀 One-Click Install

Download the latest version:

📦 6.3 MB • 🎨 Pure Three.js • 📱 AR-Tested • 🐛 Bug Fixes

Double-click to install! No terminal commands, no configuration files.

✨ What's New

Latest Updates (v0.2.10) 🐛

FIXED: ECS ATTRIBUTE ERRORS

• 🐛 Fixed "No attribute registered" Error - Disabled broken animation tools

• ❌ Broken Tools Removed - desktop_add_rotation_animation and desktop_add_scale_animation disabled

• ✅ Use Three.js Animations - All animations now use desktop_add_threejs_script

• 🎯 No More Runtime Errors - Zero ECS attribute errors in Desktop projects

• 📝 Helpful Error Messages - Broken tools now guide you to the correct approach

• 🚀 Stable & Reliable - All working tools tested and verified

Previous Updates (v0.2.9) 🔥

A-FRAME COMPONENTS COMPLETELY REMOVED

• 🗑️ Deleted All A-Frame Components - Removed particleSystem.js, audioController.js, gestureHandler.js, physicsHelper.js

• ✅ No More AFRAME Errors - Zero chance of "Can't find variable: AFRAME" errors

• ⚠️ Clear Tool Warnings - A-Frame tools now clearly marked as "WEB PROJECTS ONLY"

Previous Updates (v0.2.8) 📚

Documentation Clarity

• 🎯 Documentation Added - Clear explanation: Desktop = Three.js, NOT A-Frame

• ✅ No More Confusion - A-Frame is only for web projects, not Desktop

• 📚 DESKTOP_THREEJS_ONLY.md - Complete guide to proper Desktop development

• 🛠️ Right Tools - Use desktop_add_threejs_script for Desktop projects

Previous Updates (v0.2.7) 🛡️

AFRAME Safety Checks (for web projects only)

• 🛡️ Safe AFRAME Registration - All components now check for AFRAME before registering

• ⏱️ Load Event Waiting - Components wait for window 'load' event before initialization

• 🐛 Zero Runtime Errors - Eliminated "Can't find variable: AFRAME" errors

• 📝 Comprehensive Logging - Detailed console messages for debugging

• ✅ Graceful Fallback - Helpful error messages guide users to add A-Frame if needed

• 🔄 Webpack HMR Compatible - No more disconnection issues

Previous Updates (v0.2.6) 🚀

Three.js is Now the Default Framework!

• 🎯 Three.js Default - All new projects now default to Three.js instead of A-Frame

• 🐛 Mobile Fixes - Eliminated A-Frame loading errors on mobile devices

• ✅ Better Compatibility - Improved mobile browser support with pure Three.js

• 🔄 Auto-Fallback - Scene tools automatically use Three.js when engine is unknown

• 📚 Full Documentation - Comprehensive migration guide and updated templates

• ⚡ No Breaking Changes - A-Frame still supported via explicit template parameter

Previous Updates (v0.2.5) 🎨

Three.js Script Generator

• 🎯 desktop_add_threejs_script - Generate battle-tested Three.js scripts for AR interactions

• ✅ Proper XR8 Integration - Handles pipeline initialization, scene access, and camera setup correctly

• 📱 AR-Tested - Works perfectly on mobile devices with touch/click interactions

• 🎨 Interactive Objects - Creates tap-to-change-color spheres, particle systems, and more

• 📍 Optimal Positioning - Places objects 5m ahead at eye level with proper FOV

• 🐛 Comprehensive Logging - Detailed debugging output for troubleshooting

• 📦 6.3 MB - Includes all dependencies and templates

Previous Updates (v0.2.4)

• 🤖 AI-Powered AR Creation - Create complete AR experiences from natural language

• 🎨 6 Experience Templates - Light painting, model showcase, portals, face filters

• 💻 Code Generation - Generate custom JavaScript components

• 🧩 Custom Components - Add and manage A-Frame components

• 🔍 Unified Asset Discovery - Search PolyHaven assets with recommendations

• 🎯 Smart Orchestration - Analyzes requests and chains tools automatically

🎯 Features

🛠️ 66+ Tools for Advanced AR Development

🤖 AI-Powered Creation (NEW!)

• Smart Orchestration - create_ar_experience - Build complete AR experiences from descriptions

• Pattern Recognition - Automatically identifies AR experience types (face tracking, image targets, etc.)

• Code Generation - Generate custom JavaScript from natural language

• Experience Templates - 6 pre-built templates (light painting, portals, face filters, etc.)

🧩 Custom Development (NEW!)

• Custom Components - Add and manage A-Frame components

• Asset Discovery - Search PolyHaven with smart recommendations

• Code Templates - Pre-built particle systems, gesture handlers, audio controllers

• JavaScript Validation - Check code for errors before deployment

🎨 Scene Building

• Desktop Scene Building - Add shapes, models, lights, and animations

• AR Features - Image targets, face tracking, world tracking

• Animation System - Rotation, scale, and model animations

• Physics - Add physics to objects (dynamics, mass, gravity)

📦 Asset & Project Management

• Asset Management - Search PolyHaven, download models, manage files

• Project Tools - Create, edit, and manage 8th Wall Desktop projects

• Dev Server - Built-in preview server for testing

🎨 Natural Language Scene Building

🔧 Three Operation Modes

1. Local Mode (Default) - Work with 8th Wall Desktop projects locally

2. Docs Mode - Access 8th Wall documentation

3. API Mode - Integrate with 8th Wall Cloud (requires API key)

📦 Installation

Option 1: One-Click Install (Recommended)

1. Download the mcp-8thwall-0.1.0.mcpb file

2. Double-click to open with Claude Desktop

3. Click Install when prompted

4. Done! All 47 tools are now available

Option 2: Manual Installation

1. Clone the repository:

   git clone https://github.com/superdwayne/8thwallmcp.git cd mcp-8thwall

2. Install dependencies:

   npm install

3. Build:

   npm run build

4. Add to Claude Desktop config (~/.claude/claude_desktop_config.json):

5. Restart Claude Desktop

🎮 Quick Start

Create Your First AR Scene

1. Set your project:

   "Set my project to my-ar-project"

2. Add 3D content:

   "Create a red spinning cube at position (0, 1, -2)"

3. Add animations:

   "Make the cube pulse between 80% and 120% size"

4. Add AR features:

   "Enable face tracking with a debug mesh"

Work with 8th Wall Desktop

Search for Assets

🔧 Desktop Scene Building Tools

Primitives & Shapes

• desktop_add_shape - Add 3D primitives:

  • Geometries: box, sphere, cylinder, cone, plane, circle, torus, ring

  • Materials: basic, standard, phong

  • Properties: color, roughness, metalness, opacity, emissive

  • Hider materials: colorWrite, depthWrite, depthTest (for AR portals)

3D Models

• desktop_add_model - Add GLB/GLTF models:

  • Load from assets/ folder

  • Position, rotation, scale

  • Animation playback

  • Physics support (static, dynamic, kinematic)

Animations

• desktop_add_rotation_animation - Spin objects:

  • Axis selection (X, Y, Z)

  • Speed control

  • Loop and reverse options

  • Easing functions

• desktop_add_scale_animation - Pulse/breathe effects:

  • Min/max scale

  • Duration control

  • Loop and reverse

  • Easing functions

• desktop_set_model_animation - Control model animations:

  • Play specific animation clips

  • Loop control

  • Playback speed

AR Features

• desktop_enable_face_tracking - Face AR experiences

• desktop_add_image_target - Image tracking

• desktop_add_video - Video textures

• Hider materials for AR portals

📚 Documentation

Tool Categories

• project_get_root / project_set_root - Manage project directory

• desktop_list_projects / desktop_set_project - 8th Wall Desktop projects

• project_get_info - Get project structure

• project_list_files - List files

• project_read_file / project_write_file - File operations

• project_delete_file / project_move_file - File management

• project_scaffold - Create new project

• project_export_zip - Export for upload

• desktop_add_shape - Primitives (box, sphere, etc.)

• desktop_add_model - GLB/GLTF models

• desktop_add_rotation_animation - Spin objects

• desktop_add_scale_animation - Pulse effects

• desktop_add_image_target - Image tracking

• desktop_add_video - Video textures

• desktop_enable_face_tracking - Face AR

• desktop_set_model_animation - Model animations

• desktop_read_json / desktop_write_json / desktop_patch_json - JSON manipulation

• desktop_guess_scene - Find scene files

• assets_status - Check PolyHaven availability

• assets_search_polyhaven - Search assets

• assets_polyhaven_categories - Browse categories

• assets_polyhaven_files - Get asset metadata

• assets_download_url - Download files

• assets_unzip - Extract archives

• prompts_asset_strategy - Asset guidance

• devserver_start / devserver_stop - Local preview

• health_ping - Health check

For A-Frame and Three.js projects:

• scene_detect_engine - Detect A-Frame or Three.js

• scene_add_gltf_model - Add models

• scene_set_background_color - Background

• scene_add_primitive - Primitives

• scene_add_light - Lighting

• scene_set_environment_hdr - HDR environment

• scene_add_animation - Animations

• scene_add_textured_plane - Image planes

• scene_add_orbit_controls - Three.js controls

• scene_add_grid_helper / scene_add_floor - Helpers

• docs_get_page - Fetch documentation

• docs_search - Search docs

🐛 Known Issues & Fixes

✅ Fixed in v0.1.0

• Geometry Properties Error - Fixed missing heightSegments and openEnded properties for cylinders and cones

• Color Rendering Issue - Materials now use basic type instead of standard for reliable color rendering

• Server Crashes - Fixed process lifecycle management with proper keep-alive intervals

Current Limitations

• MCPB auto-installation may require Claude Desktop restart

• Image target camera preview shows black in Desktop mode (test on phone)

• Video autoplay may require user interaction on some platforms

🏗️ Project Structure

🚀 Advanced Usage

Environment Variables

Available Modes:

• local (default) - Work with local 8th Wall Desktop projects

• docs - Access 8th Wall documentation

• api - Integrate with 8th Wall Cloud API

HTTP Bridge for n8n

Run an HTTP bridge to call tools from n8n or other automation platforms:

API Endpoints:

• GET http://localhost:8787/tools - List all tools

• POST http://localhost:8787/tool/<toolName> - Invoke a tool

Development

📖 Examples

Create an AR Beach Scene

Create an AR Portal

Image Target Experience

🤝 Contributing

Contributions are welcome! Please see:

• CONTRIBUTING.md for contribution guidelines

• CODE_OF_CONDUCT.md for our code of conduct

• SECURITY.md for security reporting

Development Workflow

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Run npm run typecheck

6. Submit a pull request

📄 License

MIT License - see LICENSE for details

🔗 Links

• 8th Wall Desktop: 8thwall.com/desktop

• Model Context Protocol: modelcontextprotocol.io

• Claude Desktop: claude.ai

• PolyHaven Assets: polyhaven.com

• GitHub Issues: Report a bug

💡 Tips

• Use desktop_list_projects to discover your 8th Wall Desktop projects

• Search PolyHaven for free 3D assets, textures, and HDRIs

• Test AR features on a phone for camera preview

• Use hider materials (colorWrite: false) for AR portal effects

• Enable physics for dynamic objects

• Use animations to bring your scenes to life

🙏 Acknowledgments

• 8th Wall for their amazing WebAR platform

• Anthropic for Claude and the MCP protocol

• PolyHaven for free 3D assets

• The MCP Community for tools and inspiration

Built with ❤️ by