8thwallmcp

🚀 8th Wall MCP Server

Build WebAR experiences with natural language using Claude Desktop and 8th Wall 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)"

✨ 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 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):

{
  "mcpServers": {
       "mcp-8thwall": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-8thwall/dist/index.js"
      ]
    }
  }
}

5. Restart Claude Desktop.

📚 Documentation

Tool Categories

🐛 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

{
  "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:

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

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 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 Dwayne Paisley-Marshall