X3D MCP Server
Web3DConsortium/x3d_mcp
Gera e valida gráficos 3D X3D compatíveis com padrões ISO
Ver no GitHubServidor MCP que expõe capacidades de geração, validação e conversão de conteúdo X3D (padrão internacional ISO/IEC 19775) para LLMs. Permite criar cenas 3D declarativas em XML, JSON e ClassicVRML com conformidade total aos padrões oficiais do Web3D Consortium, incluindo suporte a animação humanóide (HAnim).
Instalação
npx convez-ai Web3DConsortium/x3d_mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Geração de modelos 3D interativos a partir de descrições textuais
- Validação de conteúdo X3D contra padrões internacionais
- Conversão entre diferentes formatos de encoding (XML, JSON, ClassicVRML)
- Criação de cenas com animação humanóide e representações de corpo articulado
Veredito

Ferramenta especializada e robusta para integração de LLMs com ecossistema 3D web. Excelente para aplicações que demandem geração procedural de conteúdo 3D validado, mas requer domínio técnico de X3D e configuração de MCP para uso efetivo.
README
A tradução para o português deste README ainda está na fila.
x3d_mcp
Extensible 3D (X3D) Graphics is the open, royalty-free International Standard for publishing, viewing, printing, and archiving interactive 3D models on the Web. X3D further supports the Humanoid Animation (HAnim) Standard which includes full-fidelity representations for articulated skeleton and skin of the human body. These are powerful capabilities.
This open project provides a Model Context Protocol (MCP) server for generating, validating, and converting valid X3D content using assets and tools developed using the official X3D International Standards.
This project supports the AI with X3D Special Interest Group of the Web3D Consortium, merging capabilities from ricklentz/x3d_mcp and niknarra/x3d-mcp. Unless otherwise indicated for specific contributions, the default open-source license is the BSD-style Web3D Consortium Open-Source License.
Overview
x3d_mcp exposes X3D capabilities to LLMs via the Model Context Protocol (MCP). It generates spec-compliant X3D scenes in XML, JSON, and ClassicVRML encodings, with full validation against the ISO/IEC 19775 standard.
LLMs have spatial and visual understanding of 3D space. X3D (Extensible 3D) provides a declarative, XML-based means to express that understanding as valid, interoperable 3D content. This server bridges the two.
Quickstart
Prerequisites: Python 3.12+, uv, git
git clone https://github.com/Web3DConsortium/x3d_mcp.git
cd x3d_mcp
uv sync
To verify the server starts correctly:
uv run python src/server.py
The server uses stdio transport and is designed to be launched by an MCP client, not run standalone. See the client configuration sections below.
MCP Inspector
Test the server interactively using the MCP Inspector (bundled with the mcp[cli] dependency):
uv run mcp dev src/server.py
This opens a web UI where you can call each tool, inspect input schemas, and view responses — useful for verifying your setup before connecting a client.
Client Configuration
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"x3d": {
"command": "uv",
"args": ["run", "python", "src/server.py"],
"cwd": "/absolute/path/to/x3d_mcp"
}
}
}
Replace /absolute/path/to/x3d_mcp with the actual path to this repository. Restart Claude Desktop after saving.
Claude Code
Run this command from your terminal to register the server globally:
claude mcp add x3d -- uv run --directory /absolute/path/to/x3d_mcp python src/server.py
Or add it manually to ~/.claude/mcp.json:
{
"mcpServers": {
"x3d": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/x3d_mcp", "python", "src/server.py"]
}
}
}
Cursor
Add to .cursor/mcp.json in your project root (create the file if it doesn't exist):
{
"mcpServers": {
"x3d": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/x3d_mcp", "python", "src/server.py"]
}
}
}
Using --directory is more reliable than cwd for paths containing spaces. If Cursor cannot find uv, use its full path (e.g. /opt/homebrew/bin/uv on macOS).
Other MCP Clients
Any client that supports the MCP stdio transport can connect to this server. Use the following command:
uv run --directory /absolute/path/to/x3d_mcp python src/server.py
Design Decisions
Language: Python
x3d.py(PyPIx3dv4.0.65, BSD-3) -- official Web3D Consortium package, auto-generated from X3DUOMlxml-- XSD and ISO-Schematron validation, 42x faster than pure-Python alternativesFastMCP(PyPImcp) -- official Anthropic MCP SDK, decorator-based tool registration- All dependencies are BSD/MIT licensed. Project uses Web3D Consortium Open-Source License.
Two Operating Modes
Workflow Mode -- high-level tools for end-to-end scene generation. The LLM describes what it wants; the server handles construction, validation, and serialization. Fewer tool calls, higher reliability.
Granular Mode -- low-level tools for node-by-node scene construction. The LLM builds the scene graph incrementally: create nodes, set fields, add children, define routes. Full control for complex or iterative workflows.
Both modes validate output before returning it.
JSON Conversion
JSON and ClassicVRML encoding uses x3d.py's built-in .JSON() and .VRML() serialization methods. These are auto-generated from X3DUOM and produce spec-compliant output directly. The Web3D Consortium's X3dToJson.xslt is XSLT 2.0, which is incompatible with lxml (XSLT 1.0 only), so we use the native Python serialization instead.
Validation Pipeline
Four layers, matching the X3D specification's own validation hierarchy:
- Type checking at generation time --
x3d.pyenforces field types, ranges, and enumerations during scene construction - XSD validation --
lxml.etree.XMLSchemaagainstx3d-4.1.xsd(bundled with companion schemas) - JSON Schema validation --
jsonschema.Draft202012Validatoragainstx3d-4.0-JSONSchema.json(Web3D Consortium, 364$defs). Catches misspelled keys (head/meta/etc.), unknown node names insideScene, missing required fields (encoding,@version,@profile,Scene), and wrong-type values. Web3D has not yet published a 4.1 JSON Schema, so the 4.0 schema is bundled in the meantime. - Semantic checks -- imperative Python checks for authoring-level bugs XSD cannot express: missing geometry/appearance on Shapes, empty grouping nodes, duplicate DEFs, USE/DEF consistency, ROUTE field/access-type/type validity, missing Viewpoints. Adapted from niknarra/x3d-mcp (Nikhil Narra, Nicholas Polys -- Virginia Tech / Web3D Consortium).
X3DUOM as Foundation
The X3dUnifiedObjectModel-4.1.xml (X3DUOM) is the single source of truth for all 265 concrete nodes (5 new in 4.1: EnvironmentLight, FontLibrary, HAnimPose, InlineGeometry, Tangent), abstract types, simple types, and statements. It is parsed at build time to generate:
- Node/field metadata lookup tables
- containerField mapping rules
- Enumeration value sets
- Default value tables
- Inheritance hierarchy
Architecture
x3d_mcp/
src/
server.py # FastMCP server, tool registration
tools/
workflow.py # High-level scene generation tools
granular.py # Low-level node manipulation tools
validate_tool.py # Validation MCP tool wrappers
convert.py # Encoding conversion (XML, JSON, VRML)
query.py # Node/field metadata queries
render.py # X3DOM HTML page wrapper for browser viewing
scene_ops.py # Scene CRUD: modify, remove, move nodes
animate.py # Animation chain generation (TimeSensor + Interpolator + ROUTE)
prompts.py # MCP prompts for guided workflows
x3d_utils/
scene.py # Scene graph state management
x3duom.py # X3DUOM parser, node/field metadata
validation/
validate.py # XSD + JSON validation pipeline
semantic.py # Layer 4 semantic checks (DEF/USE, ROUTE validity, etc.)
schemas/ # Bundled x3d-4.1.xsd, x3d-4.1.dtd, X3DUOM 4.1
dataset/
schema.py # Canonical training example schema, normalization
normalize.py # JSONL schema normalization CLI
validate_schema.py # JSONL schema validation CLI
augment.py # Tunable augmentation pipeline CLI
filter.py # Dataset filter/split by source and token budget
generate.py # Numeric sequence example generator CLI
generators/
numeric_sequences.py # IndexedFaceSet, Extrusion, Interpolator generators
tests/
output/
logs/ # Container logs per issue number
docs/ # Research and reference documentation
Dockerfile
docker-compose.yml
pyproject.toml
README.md
MCP Tools
Workflow Tools
| Tool | Description |
|---|---|
create_scene | Generate a complete X3D scene from a natural language description. Returns validated X3D in the requested encoding (xml, json, vrml). |
create_geometry | Generate a single geometric object with material, transform, and optional animation. |
compose_scene | Combine multiple objects, lights, viewpoints, and backgrounds into a complete scene. |
Granular Tools
| Tool | Description |
|---|---|
create_node | Create an X3D node by type name. Returns a node handle for further manipulation. |
set_field | Set a field value on a node (with type validation). |
add_child | Add a child node to a parent (validates containerField rules). |
add_route | Create a ROUTE between two node fields (validates field existence and type compatibility). |
def_node | Assign a DEF name to a node. |
use_node | Reference a previously DEF'd node via USE. |
remove_node | Remove a node from the scene graph. |
get_scene | Serialize the current scene state to X3D (xml, json, or vrml). |
reset_scene | Clear all nodes and reset the scene to empty state. |
Validation Tools
| Tool | Description |
|---|---|
validate_x3d | Validate an X3D document (XML or JSON) against the XSD schema. Returns pass/fail with detailed error messages. |
validate_current_scene | Validate the current granular scene against the XSD schema. |
validate_semantic | Run semantic checks on X3D XML beyond XSD: missing geometry/appearance on Shapes, empty grouping nodes, duplicate DEFs, USE/DEF consistency, ROUTE field/access-type/type-match validity, missing Viewpoints. Returns a markdown report. |
Conversion Tools
| Tool | Description |
|---|---|
convert_x3d | Convert X3D between encodings: xml, json, vrml. Uses x3d.py native serialization. |
Query Tools
| Tool | Description |
|---|---|
list_nodes | List available X3D nodes, optionally filtered by component. |
describe_node | Get full field definitions for a node type: field names, types, defaults, ranges, access types. |
list_components | List all X3D components with their support levels. |
list_profiles | List available profiles and their component requirements. |
Render Tools
| Tool | Description |
|---|---|
x3dom_page | Wrap X3D content (full document or scene fragment) in a standalone X3DOM HTML page for browser viewing. Lowercases tag/attr names, strips namespace declarations, embeds X3DOM 1.8.2 from CDN. Adapted from niknarra/x3d-mcp. |
x3dom_starter | Return a starter X3DOM HTML page with a small example scene. Useful as a known-good baseline. |
Scene Manipulation Tools
Operate on serialized X3D content (file path or inline XML) and return the modified document. Distinct from the granular tools, which mutate the in-memory SceneManager state.
| Tool | Description |
|---|---|
modify_x3d_node | Update one or more attribute values on a DEF'd node. Field changes passed as a JSON object string. Adapted from niknarra/x3d-mcp. |
remove_x3d_node | Remove a node and its children. Identify by DEF name or by node type plus index. |
move_x3d_node | Reparent a DEF'd node. Empty new_parent_def moves it to the Scene root. Rejects moves that would create a cycle. |
Animation Tools
Generate event-driven animation in X3D content (TimeSensor + Interpolator + ROUTE chains). Adapted from niknarra/x3d-mcp.
| Tool | Description |
|---|---|
animate_x3d_node | Insert a complete animation chain for a target field. Auto-selects the interpolator from the field's type via X3DUOM (SFRotation -> OrientationInterpolator, SFVec3f -> PositionInterpolator, SFColor -> ColorInterpolator, SFFloat -> ScalarInterpolator, etc.). |
add_x3d_route | Validate and insert a single ROUTE statement, with full DEF / field / accessType / type-match checking. |
x3d_animation_info | Reference documentation for X3D's animation system. Topics: interpolators, timesensor, routes, examples, or empty for overview. |
MCP Prompts
Guided multi-step workflows. Prompts steer the LLM through the right tool sequence for tasks where ordering matters. Adapted from niknarra/x3d-mcp.
| Prompt | Argument | Description |
|---|---|---|
build_scene | description | Step-by-step guide to build an X3D scene from scratch. Covers both workflow and granular paths, validation, and X3DOM rendering. |
audit_scene | content | Audit existing X3D content for schema and authoring issues. Walks through validate_x3d, validate_semantic, describe_node, and the scene CRUD tools. |
animate_scene | target_description | Add animation. Walks through x3d_animation_info, describe_node, animate_x3d_node, validation, and rendering. |
convert_to_x3dom | -- | Convert X3D content to a browser-viewable X3DOM HTML page via validate_x3d and x3dom_page. |
Dataset Pipeline
Tools for building, normalizing, augmenting, and generating X3D training data for fine-tuning.
Schema Normalization
Normalize mixed-type metadata fields to a consistent schema:
python -m dataset.normalize input.jsonl output.jsonl --report
python -m dataset.validate_schema input.jsonl
Augmentation
Tunable augmentation with configurable instruction diversity, X3D mutation, and token budget:
python -m dataset.augment base.jsonl augmented.jsonl \
--ratio 5 --seed 42 \
--instruction-diversity 0.5 \
--x3d-mutation 0.3 \
--max-tokens 8192
Filtering
Filter by source (original/augmented) and token budget:
python -m dataset.filter input.jsonl output.jsonl --source original --max-tokens 8192
Numeric Sequence Generation
Generate training examples targeting long numeric arrays (IndexedFaceSet, Extrusion, Interpolator):
python -m dataset.generate output.jsonl \
--type all --count 50 --complexity mixed \
--validate --seed 42
X3D Standard Reference
This server targets X3D version 4.1 (candidate draft, building on ISO/IEC 19775-1:2023 v4.0).
Supported Encodings
| Encoding | Extension | Spec |
|---|---|---|
| XML | .x3d | ISO/IEC 19776-1 |
| JSON | .x3dj | ISO/IEC 19776-5 |
| ClassicVRML | .x3dv | ISO/IEC 19776-2 |
Profiles
Default profile is Interchange (static geometry, textures, lighting, navigation). Automatically upgraded to Immersive or Full when the scene uses sensors, animation, scripting, or advanced components.
| Profile | Use Case |
|---|---|
| Core | Minimal baseline |
| Interchange | Asset sharing, static 3D models |
| Interactive | User interaction, basic behaviors |
| Immersive | Sensors, animation, scripting, physics |
| Full | Everything |
| CADInterchange | Engineering / product design |
Key Components (37 total)
Geometry3D, Shape, Grouping, Rendering, Lighting, Texturing, Navigation, EnvironmentalEffects, Interpolation, PointingDeviceSensor, EnvironmentalSensor, KeyDeviceSensor, EventUtilities, Sound, Text, Scripting, Shaders, NURBS, Geospatial, HAnim, CADGeometry, RigidBodyPhysics, ParticleSystems, VolumeRendering, Followers, Picking, Layering, Layout, Texturing3D, CubeMapTexturing, TextureProjection, Annotation, DIS, Core, Time, Networking, Geometry2D.
Full node reference: docs/x3d-node-reference.md
Dependencies
| Package | Version | Purpose |
|---|---|---|
mcp | >=1.7 | MCP SDK (FastMCP) |
x3d | >=4.0.65 | Official X3D scene construction and type validation |
lxml | >=6.0 | XSD validation, Schematron validation, XSLT transforms |
xmlschema | >=4.3 | Pure-Python XSD validation (fallback) |
jsonschema | >=4.26 | JSON Schema validation for X3D JSON encoding |
Docker
All code lives on the host. Docker is used for testing and validation only.
docker compose up --build
The container mounts src/ and tests/ from the host. Logs are written to output/logs/.
Reference Documentation
| Document | Description |
|---|---|
| docs/x3d-standard-overview.md | ISO standards, scene graph architecture, profiles, components, field types, execution model |
| docs/x3d-file-structure.md | Minimal valid files (XML/JSON/VRML), DOCTYPE declarations, encoding rules, 4-layer validation |
| docs/x3d-node-reference.md | All ~260 nodes organized by component with descriptions |
| docs/x3d-examples.md | Code patterns from hello world through PBR and animation. Links to 4,142+ Web3D example scenes |
| docs/x3d-tools-and-references.md | URLs for schemas, DTDs, X3DUOM, validators, viewers, converters, libraries |
| docs/x3d-validation-strategy.md | Validation approach: X3DUOM parsing, XSD, Schematron, containerField rules |
| docs/ecosystem-research.md | Survey of existing tools, Python vs TypeScript analysis, community resources |
External References
- X3D Specification (v4.1 draft): https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/Architecture.html
- X3D Specification (v4.0): https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-WD2/Part01/Architecture.html
- X3D Tooltips (HTML): https://www.web3d.org/x3d/tooltips/X3dTooltips.html
- X3D Tooltips Profile (XML): https://www.web3d.org/x3d/tooltips/x3d-4.0.profile.xml
- X3D Examples Archive: https://www.web3d.org/x3d/content/examples/X3dForAdvancedModeling/
- X3D Resources: https://www.web3d.org/x3d/content/examples/X3dResources.html
- X3D Schemas and DTDs: https://www.web3d.org/specifications/
- X3D Unified Object Model: https://www.web3d.org/specifications/X3DUOM.html
- X3D Schematron QA: https://www.web3d.org/x3d/tools/schematron/X3dSchematron.html
- X3D JSON Encoding (19776-5): https://www.web3d.org/documents/specifications/19776-5/V3.3/Part05/concepts.html
- x3d.py Python Package: https://www.web3d.org/x3d/stylesheets/python/python.html
- MCP Specification: https://modelcontextprotocol.io/specification/2025-11-25
- FastMCP Documentation: https://gofastmcp.com/servers/tools
- Web3D Consortium: https://www.web3d.org
Acknowledgments
The following features were adopted based on guidance from Nikhil Narra (@niknarra), Nicholas Polys (@npolys), and Don Brutzman (@brutzman) of the Web3D Consortium and X3D AI Working Group:
- Semantic validation (Validation Tools, Layer 4 of the pipeline) -- DEF/USE consistency, ROUTE validity, Shape completeness, empty-group detection, missing-Viewpoint advisory
- Animation tools -- TimeSensor + Interpolator + ROUTE chain auto-generation, single ROUTE insertion with type checking, animation reference docs
- X3DOM rendering -- standalone HTML page wrapper for browser preview
- Scene CRUD -- modify/remove/move operations on serialized X3D content with cycle detection
- MCP guided prompts --
build_scene,audit_scene,animate_scene,convert_to_x3dom
Reference implementation: niknarra/x3d-mcp. Related published work:
- Nikhil Narra, Anuj Marisetty, Nicholas Polys, and Ben Sandbrook. X3Test: A Headless Browser-Based Framework for Automated Performance Benchmarking of X3D/X3DOM Scenes. Proceedings of the 30th International Conference on 3D Web Technology (Web3D '25), Siena, Italy, September 9-10, 2025. ACM, ISBN 979-8-4007-2038-3. doi:10.1145/3746237.3746315 -- 3rd place, Web3D 2025 Tools Competition. Repo: VT-Visionarium/X3Test. VTechworks copy: 471dddd8.
- Earlier work probing visual/spatial knowledge in LLMs: doi:10.1145/3665318.3677159, with the LLM-generated X3D Model Browser as an empirical artifact.
Coordination ongoing via the X3D AI Working Group (ai@web3d.org) and the Web3D Consortium.