Item

Requirement

OS

Windows 10/11 (macOS and Linux should work but are untested)

Host

Claude Desktop, Codex, or any MCP client that speaks stdio

Python

3.10+

uv

Install uv

Account

A Trimble ID with access to your Trimble Connect projects

Variable

Default

Notes

TC_CLIENT_ID

—

required

TC_CLIENT_SECRET

—

required

TC_APP_NAME

Trimble_Connect_MCP

used in the OAuth scope (openid <app name>)

TC_REDIRECT_URI

http://localhost:8385/callback

must match the URL registered in the Developer Console

TC_DOWNLOAD_DIR

~/Downloads/TrimbleConnect

where downloaded files are saved

TC_TOKEN_DIR

~/.trimble_connect_mcp

where tokens and the region cache are stored

TC_ENABLE_WRITE

(off)

set to 1 to enable the write / delete / permission tools

Tool

What it does

tc_login

Sign in with Trimble ID in the browser (OAuth2 + PKCE), callback http://localhost:8385/callback. Non-blocking: past wait_seconds (default 90s) it returns pending=true and keeps listening in the background for up to 10 minutes

tc_login_cancel

Cancel a pending sign-in and release the callback port

tc_auth_status

Sign-in status, including login_in_progress

tc_write_status

Whether write mode is on, and how to turn it on

tc_list_regions

List the server regions (NA / EU / AP)

tc_list_projects

List projects across every region, filter by name, refresh=true to bypass the cache

tc_get_project

Details of one project

tc_list_project_members

Project members and their roles

tc_list_project_roles

The project's roles (ADMIN / USER)

tc_list_folder

Contents of a folder (defaults to the project root)

tc_folder_tree

Folder tree as text, bounded by depth and entry count

tc_get_file

File metadata

tc_list_file_versions

Version history of a file

tc_download_file

Download a file (default ~/Downloads/TrimbleConnect)

tc_search

Keyword search

tc_get_permissions

Read the ACL of a folder or file

tc_list_groups / tc_list_group_users

Project groups and their members

tc_api_get

Raw GET against any Core API endpoint (todos, views, releases, activities…)

Tool

What it does

Gate

tc_create_folder

Create one folder

—

tc_create_folder_structure

Create a whole tree (e.g. a CDE) from paths like 01-WIP/01-ARC; existing folders are skipped, so it is safe to re-run

—

tc_rename_item

Rename a folder or file

—

tc_move_item

Move a folder or file to another folder

—

tc_copy_file

Copy a file (server-side)

—

tc_copy_folder

Copy a folder with its contents (the server walks the tree; bounded by max_items)

—

tc_upload_file

Upload a NEW file (fails if the name already exists)

—

tc_upload_new_version

Upload a NEW VERSION of an existing file

confirm=true

tc_delete_item

Delete a folder or file (force=true for a non-empty folder)

confirm=true

Tool

What it does

Gate

tc_grant_permissions

Grant READ / FULL_ACCESS / NO_ACCESS to users or groups — merges safely by reading the current ACL and changing only the entries you name

—

tc_remove_permissions

Drop users or groups from the ACL (back to inherited access)

confirm=true

tc_set_permissions

Replace the ENTIRE ACL (advanced — wipes existing entries)

confirm=true

Tool

What it does

Gate

tc_add_project_user

Invite a user to the project by email (role: USER/ADMIN)

—

tc_update_project_user

Change a member's role

—

tc_remove_project_user

Remove a member from the project

confirm=true

tc_create_group / tc_rename_group

Create or rename a group

—

tc_add_group_users

Add members to a group

—

tc_remove_group_users

Remove members from a group

confirm=true

tc_delete_group

Delete a group (any permission granted to it is lost)

confirm=true

tc_api_write

Raw POST/PATCH/PUT/DELETE for endpoints with no dedicated tool

confirm=true

Symptom

Fix

redirect_uri mismatch on the sign-in page

The URL in the Developer Console must match TC_REDIRECT_URI character for character (Step 2)

Cannot listen on localhost port 8385

The port is taken — call tc_login_cancel, or change the port in both places (Step 2)

Browser shows connection refused on the callback page

The sign-in wait expired (10 minutes) — call tc_login again

tc_login returns pending: true

Not an error — finish signing in, then call tc_auth_status

Writing to Trimble Connect is disabled

TC_ENABLE_WRITE=1 is not set, or the host was not restarted

Refused: this would…

A destructive tool needs confirm=true — check the target, then call again

HTTP 403

Your Trimble account has no access to that project

HTTP 409 / 412 on create or upload

An item with that name exists — to overwrite, use tc_upload_new_version

No projects listed

Run tc_list_projects with refresh=true; check tc_auth_status shows the right account

ImportError: cannot import name 'MCPServer'

You are on mcp 1.x — run uv sync to get the 2.x version pinned in uv.lock

An endpoint has no dedicated tool (ToDos, Views, Releases, Activities…)

Use tc_api_get, e.g. todos?projectId=… or projects/{id}/activities