ACC MCP

MCP server that lets Claude manage an ISO 19650 / TCVN 14177 Common Data Environment on Autodesk Construction Cloud — projects, CDE folder trees, permissions, files, document status and naming compliance.

Contents

• CDE working rules

• Requirements

• Step 1 — Install

• Step 2 — Register with Claude Desktop

• Step 3 — First run

• Using with Codex

• Testing with a standalone client

• Adding a new tool

• Tool list

• Troubleshooting

• Repository layout

• License

CDE working rules

These rules are built into the server (they are part of the MCP instructions, and the destructive tools refuse to run without an explicit confirmed_by_user=true). They apply to every action on the CDE unless the user says otherwise. Các nguyên tắc này đã được nhúng vào server và áp dụng mặc định cho mọi thao tác trên CDE.

1. Never delete a file or a folder. Nothing is removed from a CDE — superseded containers are moved to the Archived area. acc_delete_folder refuses unless the user explicitly asked for the deletion. Không bao giờ xóa file hay thư mục.

2. Files are only overwritten. Upload with the same name so ACC adds a new version and the lineage is preserved. Uploading under a different name creates a separate document and orphans its history. File chỉ được ghi đè (upload cùng tên = version mới).

3. Rename only on a specific request — for both files and folders. A file name is the information-container ID and normally never changes. Use acc_rename_file (renames in place, keeps the history); never re-upload under a new name. Chỉ đổi tên khi được yêu cầu cụ thể. Folder renaming does not work through the ACC API (the API updates the internal name but not the displayName shown in ACC Docs) — ask the user to rename the folder in the ACC Docs UI, and never emulate it by deleting and re-creating the folder.

4. Change document state through metadata, not through the name: Status (suitability), Revision, Classification, Description — acc_set_custom_attributes. Status / Revision / Classification are native ACC attributes of the file naming standard; create a custom attribute only where ACC has no equivalent. Đổi trạng thái tài liệu bằng metadata, không đổi tên file.

5. Only issued/shared containers belong on the CDE. Keep work in progress (P0x.0y) outside it until it is actually shared. Chỉ đưa lên CDE bản đã thực sự chia sẻ/phát hành.

Requirements

Step 1 — Install

1.1 Create the APS app

1. Sign in at https://aps.autodesk.com with the Autodesk account you use for ACC.

2. If prompted that you have no hub: Get an APS plan → View options → pick the Free plan.

3. Create a Developer Hub if you do not have one: https://manage.autodesk.com → Products and Services → Hubs → Create hub → type APS developer hub → Create and Activate.

4. Back at aps.autodesk.com → profile menu → My applications → select your Developer Hub → Create application.

5. Application type — pick one:

   • Traditional Web App — has a Client Secret; fill in APS_CLIENT_SECRET.

   • Desktop, Mobile, Single-Page App — no secret; leave APS_CLIENT_SECRET empty (PKCE public client).

   • Server-to-Server — will not work; it has no 3-legged login.

6. Callback URL: enter exactly http://localhost:8087/callback.

7. API Access: tick Data Management API, Autodesk Construction Cloud API, BIM 360 API.

8. Save changes, then copy the Client ID (and Client Secret via Show).

1.2 Enable the Custom Integration in ACC

Required for every hub you want to reach, including in 3-legged mode.

1. Sign in at acc.autodesk.com as an Account Admin of the hub → Account Admin.

2. Left menu → Custom Integrations (some hubs: Settings → Custom Integrations) → Add custom integration.

3. Paste the Client ID, give it a display name, tick both Account Administration and Document Management → Add.

4. Make sure your Autodesk account is a member of at least one Docs project in that hub.

5. For hubs where you are not Account Admin, send the Client ID to that hub's Account Admin.

1.3 Clone and install

git clone https://github.com/nhantruong96/acc-mcp.git
cd acc-mcp
uv sync
uv run python -m acc_mcp --selfcheck

Expected last line: selfcheck OK, with tools registered 45.

Re-run uv sync after every git pull.

Or run the script, which also creates .env and prints the Claude Desktop values:

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

Extras:

uv sync --extra templates    # adds openpyxl, needed only by scripts\gen_acc_naming_template.py

1.4 Configure .env

copy .env.example .env

Fill in APS_CLIENT_ID (and APS_CLIENT_SECRET if you chose Traditional Web App). Never commit .env; it is in .gitignore.

Instead of .env, you can put the same variables in the env block of the Claude Desktop config in Step 2.

Step 2 — Register with Claude Desktop

1. Open the config file:

   • Microsoft Store build: %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

   • Classic installer: %APPDATA%\Claude\claude_desktop_config.json

   • Or in the app: Settings → Developer → Edit Config.

2. Add the acc block inside mcpServers, keeping any other servers:

{
  "mcpServers": {
    "acc": {
      "command": "C:\\path\\to\\acc-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "acc_mcp"],
      "env": {
        "APS_CLIENT_ID": "PASTE_CLIENT_ID_HERE",
        "APS_CLIENT_SECRET": "PASTE_SECRET_OR_LEAVE_EMPTY",
        "APS_CALLBACK_URL": "http://localhost:8087/callback",
        "APS_REGION": "US",
        "ACC_AUTH_MODE": "3lo",
        "ACC_MCP_NAMING_CONFIG": "iso19650-uk"
      }
    }
  }
}

3. Save, fully quit Claude Desktop (right-click the tray icon → Quit), then reopen it.

4. Settings → Developer must show acc as running.

Step 3 — First run

In a new conversation, ask in plain language:

1. "Check the ACC authentication status" → acc_auth_status — expect app_configured: true, auth_mode: 3lo.

2. "Sign me in to Autodesk" → acc_login — a browser opens; sign in and click Allow.

3. "Which hubs and projects can I see?" → acc_whoami → acc_list_hubs → acc_list_projects.

Set up a CDE for one project, in this order:

1. "Create an ACC project named [name], type [Street/Bridge/…], job number [no.], timezone Asia/Bangkok" → acc_create_project.

2. "Check whether the project products are active yet" → acc_get_project — wait for docs: active.

3. "Add [email] to Docs and make me project admin" → acc_add_project_user.

4. "In Project Files, build the CDE tree with disciplines […] and milestones […]" → acc_cde_structure_template → acc_create_folder_structure.

5. "Design team uploads to WIP; client gets view/download on PUBLISHED; ARCHIVED is manage-only" → acc_set_folder_permissions.

6. "Audit the naming of everything under SHARED" → acc_audit_folder_naming.

7. "Set status S4 on the files just approved" → acc_set_custom_attributes.

Conventions:

• Container ID fields, in order: Project-Originator-Volume-Level-Type-Role-Number, separator -.

• Status codes S0–S5, A1…; revision codes alphanumeric, 3–8 characters (e.g. P01, C01).

• Data Management ids carry a b. prefix; every tool accepts the id with or without it.

• Region defaults to US; pass region per call or set APS_REGION for EMEA hubs.

• Sessions last ~15 days of inactivity, then run acc_login again.

• Two actions must be done in the ACC web UI: turning on File naming standard (Docs → Files → Settings), and clicking approve/reject in Reviews.

Generate an ACC naming-standard workbook to import:

uv sync --extra templates
uv run python scripts\gen_acc_naming_template.py iso19650-uk out.xlsx --name "Project naming standard"

Then in ACC Docs → Settings → File naming standard → Import → pick out.xlsx.

Using with Codex

1. Install the server as in Step 1 — Install.

2. Open %USERPROFILE%\.codex\config.toml.

3. Add:

[mcp_servers.acc]
command = "C:\\path\\to\\acc-mcp\\.venv\\Scripts\\python.exe"
args = ["-m", "acc_mcp"]

[mcp_servers.acc.env]
APS_CLIENT_ID = "PASTE_CLIENT_ID_HERE"
APS_CLIENT_SECRET = "PASTE_SECRET_OR_LEAVE_EMPTY"
APS_CALLBACK_URL = "http://localhost:8087/callback"
APS_REGION = "US"
ACC_AUTH_MODE = "3lo"
ACC_MCP_NAMING_CONFIG = "iso19650-uk"

4. Restart the Codex CLI.

5. Run /mcp in Codex to confirm acc is listed.

Testing with a standalone client

uv run python -m acc_mcp --selfcheck
uv run acc-mcp --version
uv run acc-mcp --list-tools
npx @modelcontextprotocol/inspector uv run acc-mcp

Adding a new tool

1. Open the matching module in src/acc_mcp/tools/ (or create one).

2. Define the function and decorate it:

from ..app import mcp
from .common import api_get

@mcp.tool()
async def acc_my_tool(project_id: str) -> dict:
    """One-line summary shown to the model. Then the argument details."""
    return await api_get(f"/project/v1/projects/{project_id}")

3. If you created a new module, add it to src/acc_mcp/tools/__init__.py.

4. Never use print() — stdout is the JSON-RPC channel.

5. Verify:

uv run python -m acc_mcp --selfcheck
uv run acc-mcp --list-tools

6. Fully quit and reopen Claude Desktop.

Tool list

Add a project-specific naming convention: copy src/acc_mcp/naming_configs/iso19650-uk.json to %USERPROFILE%\.acc-mcp\naming\[project-code].json, edit the code tables, then pass config_id="[project-code]" or set ACC_MCP_NAMING_CONFIG.

Troubleshooting

Repository layout

src/acc_mcp/
  server.py          entry point (--version, --selfcheck, --list-tools)
  __main__.py        python -m acc_mcp
  app.py             FastMCP instance
  config.py          environment variables, endpoints, scopes
  auth.py            3-legged OAuth + PKCE, token storage
  http.py            APS HTTP client
  ids.py             'b.' prefix handling
  naming.py          ISO 19650 name validation / composition
  naming_configs/    bundled naming conventions (iso19650-uk.json)
  tools/             the 45 MCP tools, grouped by area
scripts/
  install.ps1                  uv sync + selfcheck
  gen_acc_naming_template.py   naming config JSON -> ACC import .xlsx
naming_templates/
  Default_ISO_19650_master.xlsx   Autodesk master workbook used as the mould
pyproject.toml       dependencies and console script
uv.lock              committed on purpose so `uv sync` is reproducible
.env.example         template for .env (never commit .env)

License

MIT — see LICENSE.