Upper Route Planner — MCP Server

A Model Context Protocol server for Upper Route Planner. It exposes Upper's route, stop, driver, vehicle, and analytics APIs as 67 tools that any MCP client — Claude Code, Claude Desktop, Claude.ai, or your own — can call.

Manage delivery operations conversationally: create and optimize routes, add stops, assign drivers, track progress, pull reports, download manifests, and share route links.

Features

• 67 tools spanning routes, stops, drivers, contacts, recurring routes, notifications, tasks, reports, tracking, analytics, vehicles, proof of delivery, zones, timesheets, archiving, manifests, and route sharing.
• Two transports from one codebase:
  • STDIO (upper-mcp-server) — for local use with Claude Code / Claude Desktop.
  • HTTP Streamable (upper-mcp-http) — for remote/hosted use with Claude.ai and other clients, with per-session token auth.
• Simple x-api-token authentication against Upper's external (ext-*) API.

Requirements

• Node.js ≥ 18
• An Upper Route Planner account with an API token (see Getting an API token).

Installation

npm install -g upper-mcp-server

Or run on demand with npx upper-mcp-server.

Configuration

The server is configured entirely through environment variables.

| Variable | Required | Used by | Description | |---|---|---|---| | UPPER_API_URL | ✅ | both | Upper API base URL, e.g. https://crew.upperinc.com (domain only; /api/v1 is appended automatically). UPPER_API_BASE_URL is accepted as an alias. | | UPPER_API_TOKEN | ✅ (STDIO) | STDIO | Your Upper API token. For HTTP, the token is supplied per request via headers instead. | | PORT | – | HTTP | HTTP port (default 3001). | | HOST | – | HTTP | Bind address (default 0.0.0.0). |

Usage

Claude Code

claude mcp add upper \
  --env UPPER_API_URL=https://crew.upperinc.com \
  --env UPPER_API_TOKEN=your_api_token \
  -- npx -y upper-mcp-server

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "upper": {
      "command": "npx",
      "args": ["-y", "upper-mcp-server"],
      "env": {
        "UPPER_API_URL": "https://crew.upperinc.com",
        "UPPER_API_TOKEN": "your_api_token"
      }
    }
  }
}

HTTP (remote / hosted)

Start the HTTP server (the token is provided by clients, not the server env):

UPPER_API_URL=https://crew.upperinc.com upper-mcp-http

Clients connect to http://<host>:3001/mcp and authenticate per session with either header:

• X-Api-Token: <your-upper-api-token>, or
• Authorization: Bearer <your-upper-api-token>

A health check is available at GET /health.

Getting an API token

Generate an API token from your Upper Route Planner account settings (API / integrations section). The token must belong to an active account; some tools require a plan that includes external API access.

Tool catalog

Account (1)

• get_account_summary — account overview: name, email, role, plan, route/driver counts.

Routes (5)

• list_routes · create_route · get_route · update_route · delete_route

Stops (4)

• list_stops · create_stop · update_stop · delete_stop

Drivers (2)

• list_drivers · assign_drivers

Operations (3)

• optimize_route · get_optimization_status · share_route

Fields (4)

• get_custom_fields · update_custom_fields · get_capacity_fields · update_capacity_fields

Contacts (8)

• list_contacts · get_contact · create_contact · update_contact · delete_contact · search_contacts · get_contact_custom_fields · update_contact_custom_fields

Recurring Routes (7)

• list_recurring_routes · get_recurring_route · create_recurring_route · update_recurring_route · delete_recurring_route · preview_recurring_route · generate_recurring_routes

Notifications (3)

• get_notification_settings · update_notification_settings · get_stop_type_notification_settings

Tasks (4)

• list_tasks · create_task · update_task · delete_task

Reports (3)

• get_delivery_report · get_route_summary · get_sms_email_report

Route Operations (5)

• duplicate_route · lock_route · reverse_route · publish_route · mark_route_complete

Stop Operations (2)

• reorder_stop · assign_stops_to_driver

Tracking (2)

• get_driver_locations · get_route_progress

Analytics (2)

• get_dashboard_metrics · get_driver_performance

Vehicles (3)

• list_vehicles · get_vehicle · get_vehicle_issues

Delivery Proof (2)

• get_delivery_proof · get_stop_logs

Zones (1)

• list_zones

Timesheets (1)

• get_timesheets

Archive (3)

• list_archived_routes · archive_route · restore_route

Route Sharing (2)

• download_manifest — get a link that opens the route's print manifest in the Upper app (login required); the app renders it for print / save-as-PDF.
• get_route_share_url — get a link to view the optimized route in the Upper app (login required); optionally also deliver the driver share link via SMS/email with send_via.

Development

npm install
npm run build      # compile TypeScript to build/
npm run dev        # tsc --watch
npm start          # run the STDIO server
npm run start:http # run the HTTP server

Testing

The test runners exercise all 67 tools in-process via the MCP InMemoryTransport and require live API credentials:

UPPER_API_URL=https://teamapi.upperinc.com \
UPPER_API_TOKEN=your_api_token \
npm test                          # protocol-compliance run across all tools

For a detailed, dependency-aware run that creates and cleans up real test data:

UPPER_API_URL=... UPPER_API_TOKEN=... node test/test-each-tool.mjs
# add --no-cleanup to leave test data in place

License

MIT © Upper Inc