# 8th Wall MCP Server
> Build WebAR experiences with natural language using Claude Desktop and 8th Wall Desktop
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
## š One-Click Install
**Download the latest version:**
[](https://github.com/superdwayne/8thwallmcp/releases/download/v0.2.13/mcp-8thwall-0.2.12.mcpb)
**š¦ 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**
```
"Create a spinning red cube with a metallic sphere orbiting around it"
"Add a beach ball with physics that falls when the scene starts"
"Create an AR portal using hider materials"
"Add an image target experience with a video"
```
### š§ **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](https://github.com/superdwayne/8thwallmcp/releases/latest/download/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:**
```bash
git clone https://github.com/superdwayne/8thwallmcp.git
cd mcp-8thwall
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build:**
```bash
npm run build
```
4. **Add to Claude Desktop config** (`~/.claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"mcp-8thwall": {
"command": "node",
"args": [
"/absolute/path/to/mcp-8thwall/dist/index.js"
]
}
}
}
```
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
```
"List all my 8th Wall Desktop projects"
"Set project to beach-scene"
"Add a seagull GLB model from assets at position (0, 2, 0)"
"Add physics to the beach ball"
"Make the rocket orbit the planet"
```
### Search for Assets
```
"Search PolyHaven for space textures"
"Download the damaged helmet GLB"
"Add the downloaded model at position (0, 1.5, -3)"
```
---
## š§ 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
<details>
<summary><b>Project Management (12 tools)</b></summary>
- `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
</details>
<details>
<summary><b>Scene Building (13 tools)</b></summary>
- `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
</details>
<details>
<summary><b>Asset Management (8 tools)</b></summary>
- `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
</details>
<details>
<summary><b>Development Tools (3 tools)</b></summary>
- `devserver_start` / `devserver_stop` - Local preview
- `health_ping` - Health check
</details>
<details>
<summary><b>Web Scene Tools (11 tools)</b></summary>
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
</details>
<details>
<summary><b>Documentation (2 tools)</b></summary>
- `docs_get_page` - Fetch documentation
- `docs_search` - Search docs
</details>
---
## š 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
```
mcp-8thwall/
āāā src/
ā āāā index.ts # Server entry point
ā āāā tools/
ā ā āāā desktop.ts # 8th Wall Desktop tools
ā ā āāā scene.ts # Web scene tools
ā ā āāā project.ts # Project management
ā ā āāā assets.ts # Asset tools
ā ā āāā devserver.ts # Dev server
ā ā āāā docs.ts # Documentation tools
ā āāā clients/
ā ā āāā 8thwallClient.ts # API client
ā āāā utils/
ā āāā projectRoot.ts # Project root management
āāā dist/ # Compiled JavaScript
āāā manifest.json # MCPB manifest
āāā mcp-8thwall-0.1.0.mcpb # Desktop Extension package
āāā README.md # This file
```
---
## š Advanced Usage
### Environment Variables
```json
{
"mcpServers": {
"mcp-8thwall": {
"command": "node",
"args": ["/path/to/dist/index.js"],
"env": {
"MODE": "local",
"PROJECT_ROOT": "/path/to/your/project",
"EIGHTHWALL_DESKTOP_ROOT": "~/Documents/8th Wall"
}
}
}
}
```
**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:
```bash
HTTP_PORT=8787 MODE=local PROJECT_ROOT=./project npm run http
```
**API Endpoints:**
- `GET http://localhost:8787/tools` - List all tools
- `POST http://localhost:8787/tool/<toolName>` - Invoke a tool
### Development
```bash
npm run dev # Run with ts-node
npm run build # Compile TypeScript
npm run typecheck # Type checking only
npm run pack:dxt # Create MCPB package
```
---
## š Examples
### Create an AR Beach Scene
```
1. "Set project to beach-scene"
2. "Add a blue sphere for the sky at (0, 50, 0) with radius 100"
3. "Add a sandy plane as the ground at (0, 0, 0)"
4. "Download a seagull GLB and add it flying at (2, 5, -10)"
5. "Make the seagull rotate slowly on the Y axis"
6. "Add a beach ball with physics at (0, 2, -3)"
```
### Create an AR Portal
```
1. "Set project to portal-demo"
2. "Create a portal using hider materials"
3. "Add a rotating torus as the portal ring"
4. "Add a blue emissive sphere as the portal glow"
5. "Make the glow pulse between 80% and 120%"
```
### Image Target Experience
```
1. "Set project to image-target-demo"
2. "Add an image target for 'poster.jpg'"
3. "Add a video plane with 'promo-video.mp4'"
4. "Add a GLB model that appears on the image"
5. "Make the model spin on the Y axis"
```
---
## š¤ Contributing
Contributions are welcome! Please see:
- [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our code of conduct
- [SECURITY.md](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](LICENSE) for details
---
## š Links
- **8th Wall Desktop**: [8thwall.com/desktop](https://www.8thwall.com/desktop/)
- **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- **Claude Desktop**: [claude.ai](https://claude.ai/)
- **PolyHaven Assets**: [polyhaven.com](https://polyhaven.com/)
- **GitHub Issues**: [Report a bug](https://github.com/superdwayne/8thwallmcp/issues)
---
## š” 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 [Dwayne Paisley-Marshall](https://github.com/superdwayne)**
