AECDM Claude Skill + MCP Server

Query Autodesk's AEC Data Model (AECDM) GraphQL API from within Claude Desktop, powered by structured Skill documentation that teaches Claude how to construct correct queries and an MCP Server that handles authentication, model browsing, 3D visualization, and query execution.

What's Included

Prerequisites

• Claude Desktop (latest version with MCP support)
• Node.js v18 or later
• An Autodesk Platform Services (APS) application registered at the Autodesk Developer Portal
  • The app must be type "Desktop, Mobile, Single-Page App" using the Authorization Code with PKCE grant type (public client, no client secret needed)
  • Add http://localhost:5001/ as a Callback URL in your app settings
  • Required scopes: data:read, viewables:read

Installation

1. Clone the Repository

git clone https://github.com/<your-username>/aecdm-claude-skill.git

2. Add the Skill Documentation to a Claude Project

The SKILL/ folder contains structured documentation that Claude reads at query time. To make it available in Claude Desktop, create a Project with the skill content as custom instructions:

1. Open Claude Desktop and create a new Project (e.g., "AECDM Queries")
2. In the Project's custom instructions, paste the contents of SKILL/SKILL.md
3. Upload the instructional and reference documents from SKILL/instructions/ and SKILL/references/ as Project Knowledge files

The skill includes:

• SKILL.md - Entry point with retrieval rules, anti-patterns, and workflow instructions
• instructions/ - Semantic guidance (how to think about queries, traversals, filters)
• references/ - Schema reference (exact field names, types, enums, input shapes)

Tip: At minimum, add SKILL.md as custom instructions and upload instructions/00_start_here.md and instructions/02_core_object_model.md as knowledge files. The remaining documents can be uploaded as needed or all at once for comprehensive coverage.

3. Install the MCP Server

cd mcp-aecdm-hybrid
npm install
npm run build

This compiles:

• The React UI (hub browser) via Vite into build/dist/
• The MCP server (TypeScript) via tsc into build/server.js

4. Configure the MCP Server in Claude Desktop

Add the server to your Claude Desktop MCP configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aecdm-hybrid": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\mcp-aecdm-hybrid\\build\\server.js"],
      "env": {
        "CLIENT_ID": "YOUR_APS_CLIENT_ID"
      }
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aecdm-hybrid": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-aecdm-hybrid/build/server.js"],
      "env": {
        "CLIENT_ID": "YOUR_APS_CLIENT_ID"
      }
    }
  }
}

Replace:

• The path in args with the absolute path to mcp-aecdm-hybrid/build/server.js on your machine
• YOUR_APS_CLIENT_ID with your Autodesk Platform Services application Client ID

After saving the configuration, restart Claude Desktop for the changes to take effect.

Running

After installation, open Claude Desktop and start a conversation within your AECDM Project (or any conversation where the MCP server is available).

Authenticating

When you first interact with the AECDM tools, Claude will call the authenticate tool. This opens your default browser to the Autodesk login page. After signing in, the OAuth token is stored in the server's memory for the duration of the session.

Browsing Models

Ask Claude to browse your ACC models, or it will automatically open the browser when needed:

"Show me my ACC projects" "Browse my Autodesk Construction Cloud models"

The in-app hub browser lets you navigate Hubs > Projects > Models and select a model to load.

Viewing 3D Models

When you select a model in the browser (or ask Claude to render one), the server opens an external browser window with the Autodesk Viewer. The viewer connects to the MCP server via WebSocket and stays synchronized - you can switch models from the in-app browser and the viewer updates automatically.

Querying the AECDM API

Once a model is loaded, ask Claude to query it using natural language:

"List all the walls in this model" "What levels does this model have?" "Find all doors on Level 1" "Show me the properties of the windows" "Get all furniture on the ground floor and highlight them"

The Skill documentation guides Claude through:

1. Calling get-model-context to retrieve the current elementGroupId
2. Constructing a valid GraphQL query following AECDM schema rules
3. Executing the query via execute-query
4. Chaining multi-step queries when needed (e.g., discovering levels before filtering by one)
5. Highlighting results in the 3D viewer via highlight-elements

MCP Tools Reference

Architecture

┌──────────────────────────────────────────────────────┐
│                  Claude Desktop                      │
│                                                      │
│  ┌──────────────┐    ┌────────────────────────────┐  │
│  │  Claude +    │◄──►│   MCP Server (stdio)       │  │
│  │  AECDM Skill │    │   - OAuth PKCE auth        │  │
│  └──────────────┘    │   - GraphQL execution      │  │
│                      │   - Model context tracking │  │
│  ┌──────────────┐    │                            │  │
│  │  In-App UI   │◄──►│   (registerAppTool /       │  │
│  │  Hub Browser │    │    registerAppResource)    │  │
│  └──────────────┘    └────────────┬───────────────┘  │
│                                   │ WebSocket        │
└───────────────────────────────────┼──────────────────┘
                                    │
                      ┌─────────────▼──────────────┐
                      │   External Browser Window  │
                      │   Autodesk Viewer (3D)     │
                      │   - Model rendering        │
                      │   - Element highlighting   │
                      └────────────────────────────┘

• The Skill documentation provides Claude with structured knowledge about the AECDM GraphQL schema, valid entry points, filter patterns, and anti-patterns
• The MCP Server communicates with Claude Desktop over stdio, serves the React-based hub browser as an in-app UI, and manages an external viewer via HTTP + WebSocket
• The External Viewer renders 3D models using the Autodesk Viewer SDK in a separate browser tab

Troubleshooting