Content
# APS MCP Server
A minimal MCP server integrating Autodesk ACC APIs via APS toolkit.
## Video Overview
[](https://www.youtube.com/watch?v=pUtWc8oFCEA)
## Setup
### Option 1: Using uv (recommended)
1. Install uv if you don't have it:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. Copy `.env.sample` to `.env` and fill in your credentials:
```
cp .env.sample .env
```
3. Create and activate a virtual environment:
```
uv venv
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate
```
4. Install dependencies:
```
uv pip install -r requirements.txt
```
5. Run the MCP server:
```
python aps_dm_server.py
```
### Option 2: Using pip
1. Copy `.env.sample` to `.env` and fill in your credentials:
```
cp .env.sample .env
```
2. Create and activate a virtual environment:
```
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate
```
3. Install dependencies:
```
pip install -r requirements.txt
```
4. Run the MCP server:
```
python aps_dm_server.py
```
## Integration with Claude Desktop
To use this MCP server with Claude Desktop:
1. Make sure you have Claude Desktop installed (download from [Claude.ai](https://claude.ai/))
2. Open your Claude Desktop configuration file:
```
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
Create it if it doesn't exist.
3. Add the appropriate configuration:
**Option A: Direct Python from virtual environment (most reliable)**
```json
{
"mcpServers": {
"acc": {
"command": "/ABSOLUTE/PATH/TO/YOUR/.venv/bin/python",
"args": [
"/ABSOLUTE/PATH/TO/YOUR/aps_dm_server.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/FOLDER"
}
}
}
}
```
Replace paths with absolute paths to your environment and project.
**Option B: Using uv**
```json
{
"mcpServers": {
"acc": {
"command": "/ABSOLUTE/PATH/TO/uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/FOLDER",
"run",
"aps_dm_server.py"
]
}
}
}
```
Find the absolute path to `uv` by running `which uv` in your terminal.
4. Save the file and restart Claude Desktop completely
5. Look for the hammer icon in Claude Desktop to access the ACC tools
## macOS Specific Setup
macOS users may encounter permission issues when integrating with Claude Desktop:
1. **Permission Issues**: If you see errors like `Operation not permitted` in logs:
- Open System Preferences → Privacy & Security → Full Disk Access
- Add Terminal and Claude applications by clicking the "+" button
2. **Working Directory Issues**: If you see errors about current directory not existing:
- Always use absolute paths in your configuration
- Consider storing projects in locations with fewer permissions restrictions (e.g., Documents folder)
3. **Finding the correct Python path**: To get the exact path to your virtual environment's Python:
```
source .venv/bin/activate # Activate your environment first
which python # Get the full path
```
4. **Checking logs for troubleshooting**:
```
tail -n 50 -f ~/Library/Logs/Claude/mcp*.log
```
## Requirements
- Python 3.11 or higher
- Dependencies listed in requirements.txt
## System Architecture
This MCP server acts as a bridge between Claude AI and the Autodesk APS platform. The diagram below illustrates how data flows through the system:
1. Your query to Claude triggers tool selection
2. Claude sends MCP requests to your local server
3. The MCP server connects to APS/ACC using your credentials
4. Data flows back to Claude which processes and formats results
## Available Tools
The MCP server exposes the following tools:
- `get_hubs`: Get all available hubs
- `get_projects`: Get all projects within a hub
- `get_project_files`: Get files in a specific folder of a project
- `get_versions`: Get version information for a specific item
## Troubleshooting
If you encounter issues with Claude Desktop integration:
1. **Server not showing up**:
- Check configuration file syntax (valid JSON)
- Use absolute paths everywhere
- Restart Claude Desktop completely
2. **Permission errors**:
- Grant Full Disk Access to Terminal and Claude
- Try using Python directly rather than through uv
- Try moving the project to a location with fewer restrictions
3. **Environment errors**:
- Ensure all dependencies are installed
- Try using the direct path to Python in your virtual environment
- Check your `.env` file has correct Autodesk credentials
4. **Logs check**:
```
tail -n 50 -f ~/Library/Logs/Claude/mcp*.log
```
5. **Manual testing**:
Test your server works by running it directly:
```
cd /path/to/your/project
source .venv/bin/activate
python aps_dm_server.py
```
## Using with OpenAI Agents SDK
This project includes integration with the OpenAI Agents SDK, allowing you to use the MCP server with an OpenAI agent.
1. Make sure your `.env` file includes your OpenAI API key:
```
OPENAI_API_KEY=your_openai_api_key
```
2. Install the additional dependencies:
```
uv pip install openai>=1.31.0
```
3. Run the agent:
```
python main_agent.py
```
This will start an interactive session where you can ask the agent questions about your Autodesk projects.
## Dependencies and Licensing
This project uses the following open source components:
- **[aps-toolkit](https://github.com/chuongmep/aps-toolkit)** - A library for Autodesk Platform Services (GPL-3.0)
- **mcp** - Multimodal Capability Protocol implementation
- **python-dotenv** - Environment variable management
- **openai** and **openai-agents** - OpenAI integration
This project is licensed under the [GNU General Public License v3.0](LICENSE) as required by the aps-toolkit dependency.
## Disclaimer
This software is provided "as is", without warranty of any kind, express or implied. This is a prototype for demonstration purposes only. The author takes no responsibility for any damages or issues that may arise from using this software. Use at your own risk.
