aps-mcp-server-nodejs
Simple Model Context Protocol server built with Node.js, providing access to Autodesk Platform Services API, with fine-grained access control using Secure Service Accounts.
Overview
This MCP server enables AI assistants (like GitHub Copilot, Claude, and Cursor) to interact with your Autodesk Construction Cloud (ACC) projects through natural language. By connecting AI chat interfaces to APS APIs, you can query project data, browse files, and analyze issues without leaving your development environment.
How It Works
The Model Context Protocol (MCP) creates a standardized way for AI assistants to access external data sources:
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ VS Code + │ MCP │ aps-mcp-server │ APS │ Autodesk ACC │
│ GitHub Copilot │ ◄─────► │ (Node.js) │ ◄─────► │ Projects │
└─────────────────┘ stdio └──────────────────┘ API └─────────────────┘
- AI Client (VS Code/Claude/Cursor) sends natural language queries
- MCP Server translates queries into APS API calls using Secure Service Account credentials
- APS APIs fetch data from your ACC projects
- MCP Server returns structured data to the AI client
- AI Client formats and presents the information to you
Available MCP Tools
This server provides 18 tools across multiple functional areas:
Projects & Files (2 tools)
| Tool | Description | Parameters | Returns |
|---|---|---|---|
| getProjectsTool | Retrieves all ACC accounts and projects accessible to your service account | None | List of accounts with nested projects (IDs and names) |
| getFolderContentsTool | Browses folder and file structure within a project | accountId, projectId, folderId (optional) | List of folders and files with IDs and display names |
Issues Management (7 tools)
| Tool | Description | Parameters | Returns |
|---|---|---|---|
| getIssuesTool | Fetches all issues from a project | projectId | List of issues with IDs, titles, statuses, types, assignments, due dates, and 3D coordinates |
| getIssueTypesTool | Gets available issue types and subtypes | projectId | List of issue types with subtypes (for issue classification) |
| createIssueTool | Creates a new issue in a project | projectId, title, issueSubtypeId, status, and many optional fields | Created issue with full details including ID, display ID, and timestamps |
| getIssueDetailsTool | Retrieves detailed information about a specific issue | projectId, issueId, includeComments, includeAttachments | Complete issue details including description, assignee, dates, location, comments, attachments, custom attributes, and audit trail |
| updateIssueTool | Updates an existing issue | projectId, issueId, plus any fields to update | Updated issue details |
| addIssueCommentTool | Adds a comment to an issue | projectId, issueId, body | Comment confirmation with ID and timestamp |
| addIssueAttachmentTool | Documents the process for adding attachments to issues | projectId, issueId, fileName, fileUrl | Documentation/guidance (placeholder - requires Data Management API) |
RFIs Management (4 tools)
| Tool | Description | Parameters | Returns |
|---|---|---|---|
| listRFIsTool | Retrieves all RFIs (Requests for Information) from a project | projectId, optional filters: searchText, status, assignedTo, limit, offset | List of RFIs with IDs, titles, questions, statuses, assignments, and due dates |
| getRFITypesTool | Gets available RFI types and categories | projectId | List of RFI types for classification |
| getRFIDetailsTool | Retrieves detailed information about a specific RFI | projectId, rfiId | Complete RFI details including question, responses, attachments, workflow history, and linked documents |
| createRFITool | Creates a new RFI in a project | projectId, title, question, dueDate, assignedTo, and optional fields | Created RFI with full details including ID and timestamps |
Photos Management (2 tools) - Read-Only
| Tool | Description | Parameters | Returns |
|---|---|---|---|
| listPhotosTool | Retrieves photos and videos from a project with filtering | projectId, optional: createdFrom, createdTo, mediaType, limit, offset | List of photos/videos with IDs, names, types, creation dates, and URLs |
| getPhotoDetailsTool | Retrieves detailed information about a specific photo or video | projectId, photoId | Complete photo/video details including metadata, location, tags, and custom attributes |
Note: Photos tools require 3-legged OAuth authentication. Run npm run oauth-login before using these tools. See OAUTH_SETUP.md for details.
Important: ACC Photos API v1 is read-only. Photo uploads must be done through ACC Mobile App or Web Interface.
Submittals Management (3 tools) ⭐
| Tool | Description | Parameters | Returns |
|---|---|---|---|
| listSubmittalsTool | Retrieves all submittals from a project with filtering | projectId, optional: status, type, assignedTo, limit, offset | List of submittals with IDs, numbers, titles, statuses, types, due dates, and assignments |
| getSubmittalTypesTool | Gets available submittal types configured in the project | projectId | List of submittal types with IDs, names, codes, and workflows |
| createSubmittalTool | Creates a new submittal in a project | projectId, title, submittalTypeId, dueDate, optional: number, description, assignedTo, status | Created submittal with full details including ID, number, status, and timestamps |
Note: Submittals tools require 3-legged OAuth authentication. Run npm run oauth-login before using these tools. See OAUTH_SETUP.md for details.
VS Code MCP Client Integration
When you use this server with VS Code + GitHub Copilot:
- Configuration: The
.vscode/mcp.jsonfile tells VS Code where to find the MCP server - Connection: VS Code starts the Node.js server and connects via stdio (standard input/output)
- Authentication: The server uses Secure Service Account credentials from
.envfor API access - Tool Discovery: Copilot learns what tools are available from the server
- Natural Queries: You ask questions in Copilot Chat using plain English
- Tool Execution: Copilot decides which tools to call and with what parameters
- Response: Results are formatted and displayed in the chat interface
Example interaction:
You: "What projects do I have access to?"
Copilot: [calls getProjectsTool] → "You have 1 project: Construction: Sample Project..."
You: "List all issues"
Copilot: [calls getIssuesTool with projectId] → "You have 3 open issues..."
You: "Show me details of issue abc123"
Copilot: [calls getIssueDetailsTool] → "Issue: Concrete Surface Finish... Status: Open..."
You: "Create a new issue for the Level 2 rework"
Copilot: [calls createIssueTool] → "✅ Issue created successfully! ID: xyz789..."
You: "List all RFIs in my project"
Copilot: [calls listRFIsTool] → "You have 5 RFIs: 2 open, 3 answered..."
You: "Create an RFI about the concrete specifications"
Copilot: [calls createRFITool] → "✅ RFI created successfully! ID: rfi-001..."
You: "Show me photos from this project"
Copilot: [calls listPhotosTool] → "Found 12 photos: Site inspection, Foundation work..."
You: "Get details of photo abc123"
Copilot: [calls getPhotoDetailsTool] → "Photo: Site Inspection... Created: 2025-01-10..."
Comparison with ACC Native Features
| Feature | ACC Web Interface | ACC Project Beta | APS MCP Server |
|---|---|---|---|
| Access Method | Web browser | Web browser | AI chat in IDE |
| Query Interface | GUI navigation | Conversational AI | Conversational AI |
| Integration | Standalone app | Standalone app | Embedded in VS Code/Claude/Cursor |
| Authentication | User login | User login | Service Account (programmatic) |
| Data Access | Full ACC features | Limited to conversation context | API-based (read and write access) |
| Customization | Fixed UI | Fixed AI behavior | Custom tools & scripts |
| Use Case | Manual project management | Quick queries & assistance | Developer workflows & automation |
| Multi-Project | Switch between projects | Context limited | Access all authorized projects |
| Offline Mode | ❌ No | ❌ No | ❌ No (requires API) |
| File Upload | ✅ Yes | ✅ Yes | ❌ No (read-only for files) |
| Issue Creation | ✅ Yes | ✅ Yes | ✅ Yes (implemented) |
| Real-time Collaboration | ✅ Yes | Limited | ❌ No |
Key Differences:
- ACC Project Beta: Autodesk's native AI assistant integrated into the ACC web interface, designed for project managers and teams working directly in ACC
- APS MCP Server: Developer-focused tool that brings ACC data into your coding environment, ideal for:
- Building automation scripts
- Creating custom reports
- Integrating ACC data with other systems
- Quick project status checks without leaving your IDE
- Prototyping new ACC integrations
When to use each:
- Use ACC Web Interface for full project management, file uploads, and team collaboration
- Use ACC Project Beta for quick questions while working in ACC web
- Use APS MCP Server for development workflows, custom automation, and IDE-native queries
Customer Value & Use Cases
🎯 Value Proposition
The APS MCP Server bridges the gap between construction data and AI-powered development tools, enabling customers to:
- Reduce Context Switching - Access ACC data without leaving your IDE
- Accelerate Development - Build integrations faster with AI assistance
- Improve Data Visibility - Query project data conversationally in natural language
- Enable Automation - Foundation for building custom workflows and scripts
- Prototype Rapidly - Test API integrations before full implementation
👥 Target Customer Segments
1. Construction Technology Teams
Organizations building custom integrations on top of ACC:
- Pain Point: Manual API exploration and testing is time-consuming
- Solution: Query ACC data conversationally while writing integration code
- Example: "Show me the issue schema for this project" while building an issue tracking integration
2. BIM/VDC Developers
Developers creating automation for construction workflows:
- Pain Point: Need to understand project structure before writing automation scripts
- Solution: Explore project data, folder structures, and issue patterns without leaving the code editor
- Example: "List all RVT files and their locations" while building a model coordination script
3. System Integrators
Teams connecting ACC with other enterprise systems (ERP, PM tools):
- Pain Point: Understanding data models and testing connections across multiple systems
- Solution: Quick data validation and testing during integration development
- Example: "What fields are available in issues?" while mapping data between systems
4. DevOps/Infrastructure Teams
Teams managing APS applications and monitoring project health:
- Pain Point: Need quick insights without building full dashboards
- Solution: Ad-hoc queries for monitoring and troubleshooting
- Example: "How many open issues are in production projects?" for health checks
5. Independent Developers/Consultants
Freelancers building APS solutions:
- Pain Point: Limited time for API exploration and testing
- Solution: Rapid prototyping and validation of ideas
- Example: Test API responses before committing to implementation approach
💼 Real-World Use Cases
Use Case 1: Rapid Integration Development
Scenario: Developer building a custom dashboard that displays project issues
Traditional Workflow:
- Open browser → Navigate to APS API docs
- Set up Postman/Insomnia for API testing
- Configure authentication
- Test API endpoints manually
- Copy response structure
- Switch back to IDE
- Write code based on manual testing
With MCP Server:
- In VS Code: "Show me all issues in my project"
- Review data structure in chat
- Ask: "What fields are available for filtering?"
- Immediately start writing code with accurate data models
- Time saved: 30-60 minutes per API endpoint
Use Case 2: Project Health Monitoring
Scenario: DevOps team needs to check project status across multiple sites
Query Examples:
"How many projects do I have access to?"
"List all open issues across projects"
"Show me projects with issues overdue by more than 7 days"
"What are the most common issue types?"
"Get detailed information for issue abc123"
"Create a new issue for the concrete rework on Level 2"
Value: Quick health checks without building custom reporting tools
Use Case 3: Debugging Production Issues
Scenario: Support team investigating customer-reported problems
Workflow:
Developer: "What issue types are available in project X?"
Copilot: [Returns actual issue types from customer's project]
Developer: "Show me all issues created in the last 24 hours"
Copilot: [Returns recent issues with details]
Developer: "Get full details for issue abc123"
Copilot: [Shows complete issue information including comments and attachments]
Developer: "Create a test issue to verify the API"
Copilot: [Creates issue and returns confirmation with issue ID]
Developer: "What's the folder structure of this project?"
Copilot: [Shows actual folder hierarchy]
Value: Faster troubleshooting with real-time data access
Use Case 4: Data Migration Planning
Scenario: Migrating data from legacy system to ACC
Queries:
"Show me the folder structure of all projects"
"What custom fields are configured for issues?"
"List all file types in the project"
"Get a sample issue with all its fields to understand the data structure"
"Create a test issue to validate the target system can receive ACC data"
Value: Understand target system structure before migration scripting
Use Case 5: Training & Documentation
Scenario: Training new developers on APS APIs
Interactive Learning:
Trainee: "What data can I get from an issue?"
Copilot: [Shows real issue structure with actual data using getIssueDetailsTool]
Trainee: "How do I create an issue?"
Copilot: [Demonstrates with createIssueTool showing required and optional fields]
Trainee: "How are folders organized?"
Copilot: [Demonstrates with live project data]
Value: Learn with real examples instead of abstract documentation
🔄 Customer Workflow Examples
For Construction Tech Companies:
Morning Standup:
PM: "What's blocking us today?"
Dev: [Opens VS Code] "Show me all high-priority issues"
Result: Team sees real blockers in 5 seconds
During Development:
Dev: "List all .dwg files in the structural folder"
Copilot: [Returns file list]
Dev: Uses list to build file processing automation
Before Deployment:
Dev: "How many projects will this affect?"
Copilot: [Lists all accessible projects]
Dev: Plans rollout strategy
For System Integrators:
Discovery Phase:
"What issue types exist?" → Map to target system
"Show me all custom attributes" → Plan data transformation
"List all projects by region" → Scope integration effort
Development Phase:
"Get sample issue data" → Test transformation logic
"What's the folder structure?" → Plan file sync strategy
"Show project metadata" → Validate connection
Testing Phase:
"Create test issue" → Validate write operations
"Get issue details" → Verify data completeness
"List recent changes" → Verify sync accuracy
📊 ROI & Metrics
Time Savings:
- API exploration: 30-60 min → 2-5 min (90% reduction)
- Data structure discovery: 45 min → 5 min (89% reduction)
- Integration prototyping: 4 hours → 1 hour (75% reduction)
Productivity Gains:
- Developers stay in IDE: 80% less context switching
- Faster debugging: Real-time data access vs manual API calls
- Reduced errors: AI-assisted queries vs manual Postman testing
Business Impact:
- Faster time-to-market for integrations
- Lower training costs for new developers
- Improved developer experience and satisfaction
- Enables rapid prototyping and innovation
🚀 Future Expansion Opportunities
Planned Enhancements:
- ✅ Issue Creation - Create new issues (IMPLEMENTED)
- ✅ Issue Details - Get detailed issue information (IMPLEMENTED)
- ⏳ Issue Updates - Update existing issues (IN PROGRESS)
- ⏳ Issue Comments - Add comments to issues (IN PROGRESS)
- ⏳ Issue Attachments - Upload files to issues (IN PROGRESS)
- 🔜 Advanced Queries: Filter, sort, aggregate data
- 🔜 Multi-Project Operations: Bulk queries across projects
- 🔜 File Operations: Upload/download files
- 🔜 Webhooks Integration: Real-time notifications in IDE
- 🔜 Cost Management: Query budget and cost data
- 🔜 Schedule Data: Access project timelines and milestones
- 🔜 RFI Management: Query and manage RFIs
- 🔜 Document Management: Search and analyze documents
Extended Use Cases:
- ✅ Issue creation from natural language descriptions
- Automated issue creation from code comments
- Project health dashboards in IDE
- Compliance checking and reporting
- Automated status updates to stakeholders
- Integration testing frameworks
- Detailed issue analysis with comments and attachments
🎓 Getting Started for Customers
For Construction Tech Teams:
- Set up Secure Service Account (15 min)
- Configure MCP server in VS Code (5 min)
- Start querying your projects (immediate)
- Build on top with custom tools (ongoing)
For Consultants/Freelancers:
- Use for rapid prototyping (Day 1)
- Validate customer requirements (Day 2-3)
- Build production integrations (Week 1+)
- Deliver faster, more accurate solutions
For Enterprise Teams:
- Pilot with 2-3 developers (Week 1)
- Measure time savings and productivity (Week 2-4)
- Roll out to entire team (Month 2)
- Expand with custom tools (Ongoing)
💡 Success Stories (Potential)
Example 1: BIM Coordination Company
- Before: 4 hours to explore API and build issue reporter
- After: 1 hour with MCP-assisted development
- Result: 75% time reduction, faster client delivery
Example 2: Construction Software Vendor
- Before: Support team manually checked API responses
- After: Instant troubleshooting with natural language queries
- Result: 60% faster issue resolution
Example 3: Enterprise General Contractor
- Before: Developers built custom API testing tools
- After: Used MCP server for all API exploration
- Result: Eliminated 20 hours/month of tool maintenance
Development
Prerequisites
- Node.js
- APS application (must be of type Server-to-Server)
- Provisioned access to ACC
Setup
Secure Service Account
Our MCP server will need a secure service account and a private key. Instead of implementing the logic in this code sample, we will use https://ssa-manager.autodesk.io:
- Go to https://ssa-manager.autodesk.io, and log in with your APS client ID and secret
- Create a new secure service account using the Create Account With Name: button; don't forget to specify the first name and last name
- Make sure the new account is selected in the Accounts list
- Make note of the
serviceAccountIdandemailvalues under Account Details - Create a new private key using the Create Key button; a *.pem file will be automatically downloaded to your machine
- Make sure the new private key is selected in the Keys list
- Make note of the
kidvalue under Key Details
Autodesk Construction Cloud
- Make sure you've provisioned access to ACC for your APS application
- Invite the secure service account (the
emailvalue from earlier) as a new member to your selected ACC projects
Server
- Clone this repository
- Install dependencies:
yarn install - Create a .env file in the root folder of this project, and define the following environment variables:
APS_CLIENT_ID- your APS application client IDAPS_CLIENT_SECRET- your APS application client secretSSA_ID- your service account ID (theserviceAccountIdfield from earlier)SSA_KEY_ID- your private key ID (thekidfield from earlier)SSA_KEY_PATH- full path to your downloaded *.pem file
- The .env file might look something like this:
APS_CLIENT_ID="AhH9..."
APS_CLIENT_SECRET="1FS4..."
SSA_ID="ZCU2TJH5PK8A5KQ9"
SSA_KEY_ID="8a4ee790-3378-44f3-bbab-5acb35ec35ce"
SSA_KEY_PATH="/Users/brozp/aps-mcp-server-nodejs/8a4ee790-3378-44f3-bbab-5acb35ec35ce.pem"
Usage
MCP Inspector
- Run the Model Context Protocol Inspector:
npx @modelcontextprotocol/inspector - Hit
Connectto connect to the MCP server
Claude Desktop
- Make sure you have Claude Desktop installed
- Create a Claude Desktop config file if you don't have one yet:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%\Claude\claude_desktop_config.json
- Add this MCP server to the config, using the absolute path of the server.js file on your system, for example:
{
"mcpServers": {
"aps-mcp-server-nodejs": {
"command": "node",
"args": [
"/path/to/aps-mcp-server-nodejs/server.js"
]
}
}
}
- Restart Claude Desktop and verify the server is running in Settings → Developer:
- Open Claude Desktop, and try some of the following test prompts:
- What ACC projects do I have access to?
- Give me a visual dashboard of all issues in project XYZ
- List all issues in my project
- Show me the folder structure
- Get detailed information for issue [issue-id]
- Create a new issue titled "Test Issue" with status "open"
Example: Visual Dashboard Generation
Claude can create interactive visualizations and dashboards from your ACC data:
The MCP server enables Claude to:
- Query real-time project data from ACC
- Generate visual dashboards with issue statistics
- Create charts showing issues by type, status, and more
- Provide detailed project insights through natural conversation
For more details on how to add MCP servers to Claude Desktop, see the official documentation.
Visual Studio Code & GitHub Copilot
- Make sure you have enabled MCP servers in Visual Studio Code
- Create .vscode/mcp.json file in your workspace, and add the following JSON to it:
{
"servers": {
"aps-mcp-server-nodejs": {
"type": "stdio",
"command": "node",
"args": [
"/path/to/aps-mcp-server-nodejs/server.js"
]
}
}
}
For more details on how to add MCP servers to Visual Studio Code, see the documentation
Cursor
- Create .cursor/mcp.json file in your workspace, and add the following JSON to it:
{
"mcpServers": {
"aps-mcp-server-nodejs": {
"command": "node",
"args": [
"/path/to/aps-mcp-server-nodejs/server.js"
]
}
}
}
For more details on how to add MCP servers to Cursor, see the documentation