Trimble Connect MCP

Trimble Connect MCP

A local (stdio) MCP server that gives Claude access to Trimble Connect:projects, folder trees, files, versions, members, groups and permissions —40 tools over the Core API v2.

Contents

• Requirements
• Step 1 — Install
• Step 2 — Register a Trimble application
• Step 3 — Configure Claude Desktop
• Step 4 — First run
• Write mode
• Other MCP clients
• Environment variables
• Tools
• Troubleshooting
• Contributing
• License

Requirements

Step 1 — Install

git clone https://github.com/nhantruong96/trimble-connect-mcp.git
cd trimble-connect-mcp
uv sync

Check that the server imports:

uv run python -c "import server; print('OK')"

Run uv sync again after every git pull.

Step 2 — Register a Trimble application

1. Go to the Trimble Developer Console and createan application.

2. Copy the Client ID and Client Secret.

3. Under Callback URLs, add exactly:

   http://localhost:8385/callback
   

4. If port 8385 is already taken, change it in both places: the Callback URLin the Developer Console and TC_REDIRECT_URI in your config (for examplehttp://localhost:8590/callback).

The redirect URI must match character for character — http://localhost withouta port, 127.0.0.1 instead of localhost, or a missing /callback will all berejected.

Step 3 — Configure Claude Desktop

Open %APPDATA%\Claude\claude_desktop_config.json (or Settings → Extensions)and add the block below, replacing the paths and the client id/secret:

{
  "mcpServers": {
    "trimble-connect": {
      "command": "C:\\path\\to\\trimble-connect-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\trimble-connect-mcp\\server.py"],
      "env": {
        "TC_CLIENT_ID": "<client id>",
        "TC_CLIENT_SECRET": "<client secret>",
        "TC_APP_NAME": "Trimble_Connect_MCP",
        "TC_REDIRECT_URI": "http://localhost:8385/callback",
        "TC_ENABLE_WRITE": "1"
      }
    }
  }
}

A ready-made template is inclaude_desktop_config.example.json.Never commit your real config — it holds the client secret.

Quit Claude Desktop completely, then reopen it.

Step 4 — First run

Ask in plain language:

"Sign in to Trimble Connect, then list my projects."

• The browser opens the Trimble ID page; once you sign in the tools are ready.
• Tokens refresh automatically — you only sign in once.
• After 90 seconds tc_login returns pending=true plus an auth_url. Finishsigning in in the browser, then ask Claude to call tc_auth_status.
• If you abandon a sign-in, call tc_login_cancel before starting a new one.
• To sign out, delete %USERPROFILE%\.trimble_connect_mcp\tokens.json.

The region (NA / EU / AP) is detected automatically and cached in%USERPROFILE%\.trimble_connect_mcp\.

Write mode

The server is read-only by default. Two gates protect every write:

1. Set TC_ENABLE_WRITE=1 in the env block of your config and restart thehost. Verify with tc_write_status.
2. Destructive tools (delete, overwrite a version, replace an ACL, remove amember) additionally require confirm=true.

There is no restore tool — Core API 2.0 has no undelete endpoint. Deleted itemscan only be recovered by hand in the Trimble Connect web interface.

Other MCP clients

1. Take the .venv\Scripts\python.exe and server.py paths from Step 3.
2. Register a stdio server using them as command and args.
3. Set the same environment variables as in Step 3.
4. Restart the client.

To check that the server starts at all:

uv run python server.py

Environment variables

Tools

Read — always available

Write — folders and files (needs TC_ENABLE_WRITE=1)

Write — permissions

Trimble Connect has only three levels: READ, FULL_ACCESS, NO_ACCESS (filesdo not support NO_ACCESS). The special id tc-groups:* means every projectmember. The underlying PATCH .../permissions overwrites the whole ACL, whichis why tc_grant_permissions / tc_remove_permissions are preferred overtc_set_permissions.

Write — members and groups

Troubleshooting

Contributing

Development setup, repository layout, and how to add a tool are inCONTRIBUTING.md.

The upstream API is https://app.connect.trimble.com/tc/api/2.0 (master, NorthAmerica); other regions are discovered through the /regions endpoint.

License

MIT