JustRouting MCP Server

JustRouting MCP

Routing, geocoding, distance matrices, and vehicle routing for AI assistants — focused on Southeast Asia.

JustRouting MCP lets MCP-compatible AI assistants such as Claude and Cursor use JustRouting for road routing, geocoding, distance and travel-time comparison, and multi-vehicle route optimization.

Designed for Southeast Asia.

Quick Start

1. Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/justrouting/mcp/main/install.sh | sh

The installer downloads the latest prebuilt binary for your platform and installs justrouting-mcp.

No Go installation is required.

From source

go install github.com/justrouting/mcp/cmd/justrouting-mcp@latest

Make sure justrouting-mcp is available in your PATH.

2. Set your API key

Get an API key from JustRouting, then set:

export JUSTROUTING_API_KEY="your-api-key"

3. Connect to Claude or Cursor

Add the following MCP server configuration:

{
  "mcpServers": {
    "justrouting": {
      "command": "justrouting-mcp",
      "env": {
        "JUSTROUTING_API_KEY": "your-api-key"
      }
    }
  }
}

The server communicates with MCP clients through stdio.

Tools

The tools are intentionally separated by task:

route = calculate table = compare optimize = decide

---

geocode

Search for a place or address and convert it into coordinates.

Use it when the user provides:

• a place name
• a landmark
• a business
• a street address
• another location description

Do not use it when the user already provides coordinates.

Input

{
  "name": "Marina Bay Sands",
  "housenumber": "10",
  "street": "Bayfront Avenue",
  "postcode": "018956",
  "city": "Singapore",
  "country": "Singapore"
}

The available fields are:

• name — place, landmark, or business name
• housenumber — house or building number
• street — street name
• postcode — postal or ZIP code
• city — city or locality
• country — country
• limit — maximum number of results, up to 10
• filters — optional search filters

Only provide fields that can be determined from the user's request. Do not invent missing address components.

Country and city can be useful for disambiguating common or abbreviated place names.

Output

{
  "results": [
    {
      "longitude": 103.859,
      "latitude": 1.2834,
      "coordinates": "103.859,1.2834",
      "formatted": "Marina Bay Sands, 10 Bayfront Avenue, 018956, Singapore",
      "place_id": "51667b3e...",
      "country_code": "sg",
      "result_type": "building"
    }
  ]
}

Results are ordered by relevance.

By default, the best matching result is returned. When multiple results are requested, choose the result that best matches the user's intended location.

The coordinates value is in longitude,latitude format and can be passed directly to route, table, or optimize.

If geocoding is used as part of a routing workflow, verify that the selected result matches the intended place before using its coordinates.

---

route

Calculate a driving route between two locations.

Use it when the user needs to:

• calculate driving distance
• estimate travel time
• get a route between two locations
• get route geometry
• understand which roads a route uses
• avoid specific road types

Input

{
  "origin": "103.8198,1.3521",
  "destination": "103.9915,1.3644"
}

Coordinates must use:

longitude,latitude

For example:

103.8198,1.3521

Optional motorcycle routing:

{
  "origin": "103.8198,1.3521",
  "destination": "103.9915,1.3644",
  "profile": "motorcycle"
}

Use profile: "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.

Otherwise, omit profile to use the default driving profile.

Avoid roads

Use exclude when the user explicitly asks to avoid a type of road.

Supported values:

• toll
• motorway
• ferry

Example:

{
  "origin": "103.8198,1.3521",
  "destination": "103.9915,1.3644",
  "exclude": ["toll"]
}

Road avoidance is a preference, not a guarantee. The routing engine avoids the specified road type when a reasonable alternative exists.

Output

{
  "distance_meters": 18500,
  "duration_seconds": 1500,
  "profile": "driving",
  "origin": {
    "input": "103.8198,1.3521",
    "snapped": [103.8197, 1.3520],
    "name": "Example Road",
    "distance": 4.2
  },
  "destination": {
    "input": "103.9915,1.3644",
    "snapped": [103.9915, 1.3644],
    "name": "Airport Boulevard",
    "distance": 8.1
  },
  "geometry": "ka|`@_ceeEnAqB...",
  "summary": {
    "roads": ["East Coast Parkway"],
    "tolls": false,
    "ferry": false
  }
}

distance_meters is the route distance in meters.

duration_seconds is the estimated travel duration in seconds.

geometry is a simplified encoded polyline that can be used to render the route on a map.

summary.roads lists the main roads used by the route.

summary.tolls indicates whether the route uses toll roads.

summary.ferry indicates whether the route includes a ferry crossing.

If the user provides place names or addresses instead of coordinates, call geocode first.

---

table

Calculate a distance and/or travel-time matrix between multiple locations.

Use it when the user needs to:

• find the nearest driver, vehicle, store, or facility
• compare several destinations
• compare multiple origin-destination pairs
• build a distance or travel-time matrix

Do not use it for a single route between two locations. Use route instead.

Input

{
  "coordinates": [
    "103.8391,1.2771",
    "103.8590,1.2834",
    "103.7986,1.2885"
  ],
  "annotations": ["distance"]
}

Each coordinate has a stable zero-based index based on its position in the coordinates list.

Matrix rows correspond to sources.

Matrix columns correspond to destinations.

A matrix value at:

[row][column]

represents the route from that source to that destination.

For example:

durations[0][2]

is the travel time from source index 0 to destination index 2.

The sources and destinations returned by the tool contain the original coordinate indices so the matrix can be mapped back to the user's locations.

Nearest-driver example

For a question such as:

Which driver is closest to this customer?

Put the customer first:

coordinates[0] = customer
coordinates[1] = driver A
coordinates[2] = driver B
coordinates[3] = driver C

Then use the customer as the source and the drivers as destinations.

Read the corresponding matrix row and choose the smallest non-null distance or duration.

Selecting sources and destinations

source and destinations can restrict the matrix to specific coordinate indices.

For example:

{
  "coordinates": [
    "103.8391,1.2771",
    "103.8590,1.2834",
    "103.7986,1.2885"
  ],
  "sources": [0],
  "destinations": [1, 2]
}

This calculates routes from coordinate 0 to coordinates 1 and 2.

Annotations

Use:

"annotations": ["duration"]

for travel times.

Use:

"annotations": ["distance"]

for distances.

Use:

"annotations": ["duration", "distance"]

for both.

If omitted, both are returned.

Output

{
  "code": "Ok",
  "durations": [
    [0, 1860, null],
    [1850, 0, 2100],
    [null, 2110, 0]
  ],
  "distances": [
    [0, 14200, null],
    [14100, 0, 18400],
    [null, 18200, 0]
  ],
  "sources": [
    {
      "index": 0,
      "name": "Duxton Road",
      "location": [103.8391, 1.2771],
      "distance": 12.3
    }
  ],
  "destinations": [
    {
      "index": 1,
      "name": "Bayfront Avenue",
      "location": [103.8590, 1.2834],
      "distance": 8.4
    }
  ]
}

durations are in seconds.

distances are in meters.

A matrix value of null means that the origin-destination pair is unreachable. Never interpret null as zero.

---

optimize

Assign jobs and shipments to vehicles and determine the order in which each vehicle should visit its stops.

Use it when the user needs to:

• assign multiple deliveries or pickups to vehicles
• plan routes for a fleet with amounts, capacity, skills, or time windows
• pair pickups with deliveries that one vehicle must serve in order
• determine the order of multiple stops
• optimize a multi-vehicle routing solution

Do not use it for a single route. Use route.

Do not use it only to compare distances between locations. Use table.

Input

{
  "vehicles": [
    {
      "id": 1,
      "start": "103.7923,1.3246",
      "end": "103.7923,1.3246"
    },
    {
      "id": 2,
      "start": "103.8232,1.3241",
      "end": "103.8232,1.3241"
    }
  ],
  "jobs": [
    {
      "id": 1,
      "location": "103.7975,1.3104"
    },
    {
      "id": 2,
      "location": "103.7843,1.3149"
    },
    {
      "id": 3,
      "location": "103.7976,1.3198"
    }
  ]
}

Each vehicle must have at least a start or an end.

For a round trip, set both to the same location:

{
  "id": 1,
  "start": "103.7923,1.3246",
  "end": "103.7923,1.3246"
}

If start or end is omitted, the vehicle may start or end anywhere.

Each vehicle and job must have a unique id. Shipment pickup ids must be unique among pickups and delivery ids among deliveries. Break ids must be unique within their vehicle.

Locations must use:

longitude,latitude

A richer example with capacity, time windows and priorities:

{
  "vehicles": [
    {
      "id": 1,
      "start": "103.7923,1.3246",
      "end": "103.7923,1.3246",
      "capacity": [1000, 4],
      "time_window": [0, 28800]
    }
  ],
  "jobs": [
    {
      "id": 1,
      "location": "103.7975,1.3104",
      "delivery": [100, 1],
      "service": 300,
      "time_windows": [[0, 14400]],
      "priority": 80
    }
  ],
  "shipments": [
    {
      "pickup": {"id": 2, "location": "103.7843,1.3149", "service": 150},
      "delivery": {"id": 3, "location": "103.7976,1.3198", "service": 150},
      "amount": [50]
    }
  ],
  "options": {"g": true}
}

Vehicle profiles

Each vehicle can use its own routing profile.

For example:

{
  "id": 1,
  "profile": "motorcycle",
  "start": "103.7923,1.3246",
  "end": "103.7923,1.3246"
}

Use "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.

Otherwise, omit profile to use the default driving profile.

Amounts and capacity

capacity on a vehicle and delivery, pickup and amount on tasks are multidimensional: one value per dimension.

{"capacity": [1000, 4]}

means 1000 kilograms and 4 pallets. Every such vector in one request must share the same length.

A vehicle serves a set of tasks only if its load never exceeds its capacity. Insufficient capacity is not an error: the task is moved to unassigned instead.

Skills

skills are integer capability tags. A task is served only by a vehicle that has all the task's skills. A task without skills can be served by any vehicle.

Time windows

A time window is an inclusive [start, end] pair in seconds. Use one clock for the whole request: either relative (for example [0, 14400] means within 4 hours of the planning start) or absolute UNIX timestamps. Early arrivals wait until the window opens. Tasks that cannot be reached in time are moved to unassigned.

Priority

priority is 0-100. When not everything fits, higher-priority tasks are kept and lower-priority ones are dropped.

Shipments

A shipment is a pickup and a delivery served in order by the same vehicle, with amount loaded at the pickup and unloaded at the delivery.

Breaks

A vehicle's breaks are rest periods with an id unique within the vehicle, optional time_windows, and a service duration in seconds.

Custom matrices

matrices supplies your own travel-time (durations), distance and cost matrices per profile ("car" or "motorcycle"). Use it only when the user supplies their own travel times; then location_index, start_index and end_index reference rows and columns instead of coordinates.

Route geometry

Set "options": {"g": true} to get an encoded polyline and distances back for every route. Use it when the user wants to draw the routes on a map.

Output

A simplified result looks like:

{
  "summary": {
    "cost": 2733,
    "routes": 2,
    "unassigned": 0,
    "duration": 2733,
    "delivery": [100, 1]
  },
  "routes": [
    {
      "vehicle": 1,
      "cost": 1144,
      "duration": 1144,
      "geometry": "encoded_polyline",
      "steps": [
        {
          "type": "start",
          "location": [103.7923, 1.3246],
          "arrival": 0
        },
        {
          "type": "job",
          "id": 2,
          "job": 2,
          "location": [103.7843, 1.3149],
          "arrival": 269,
          "duration": 269,
          "load": [50]
        },
        {
          "type": "end",
          "location": [103.7923, 1.3246],
          "arrival": 1144,
          "duration": 1144
        }
      ]
    }
  ],
  "unassigned": []
}

Read each route's steps in order to determine:

• which vehicle serves each task
• the order in which tasks are visited
• when each task is reached

pickup, delivery, and break steps may appear between the route's start and end steps. violations fields exist for API completeness and are always empty on the hosted API. geometry appears only with options.g.

Always check unassigned.

Do not assume that every task can be assigned to a vehicle.

If the user provides place names or addresses instead of coordinates, call geocode first for every location and use the selected coordinates in the optimization request.

---

Agent Workflows

JustRouting MCP is designed so that AI assistants can combine the tools into larger workflows.

Route between two places

For:

How long does it take to drive from Marina Bay Sands to Changi Airport?

The workflow is:

geocode → geocode → route

1. Geocode the origin.
2. Geocode the destination.
3. Pass the resulting coordinates to route.

If the user already provides coordinates, skip geocoding.

Find the nearest driver

For:

Which driver is closest to the customer?

The workflow is:

geocode × N → table

1. Geocode the customer.
2. Geocode each driver.
3. Keep the locations in a fixed order.
4. Use the customer as the source.
5. Use the drivers as destinations.
6. Compare the returned distances or durations.

Plan multiple vehicles

For:

I have two vans and six customers. Assign the customers to the vans and determine the stop order.

The workflow is:

geocode × N → optimize

1. Geocode each vehicle's start/end location.
2. Geocode every job location.
3. Create one vehicle entry per vehicle.
4. Create one job entry per customer.
5. Call optimize.
6. Read routes[].steps to determine each vehicle's itinerary.
7. Check unassigned for jobs that could not be served.

---

Coordinate Format

All routing tools use:

longitude,latitude

For example:

103.8198,1.3521

This is:

longitude = 103.8198
latitude  = 1.3521

Do not reverse the order.

---

Claude

Add JustRouting MCP to your Claude MCP configuration:

{
  "mcpServers": {
    "justrouting": {
      "command": "justrouting-mcp",
      "env": {
        "JUSTROUTING_API_KEY": "your-api-key"
      }
    }
  }
}

Once connected, Claude can use the JustRouting tools directly.

---

Cursor

Add JustRouting MCP to your Cursor MCP configuration:

{
  "mcpServers": {
    "justrouting": {
      "command": "justrouting-mcp",
      "env": {
        "JUSTROUTING_API_KEY": "your-api-key"
      }
    }
  }
}

Once connected, Cursor can use the JustRouting tools directly.

---

Requirements

For prebuilt binaries:

• A JustRouting API key

For installation from source:

• Go 1.25+

The MCP server currently uses stdio transport.

---

Development

Clone the repository:

git clone https://github.com/justrouting/mcp.git
cd mcp

Install dependencies:

go mod download

Run tests:

go test ./...

Build:

go build -o justrouting-mcp ./cmd/justrouting-mcp

Run:

JUSTROUTING_API_KEY="YOUR-API-KEY" ./justrouting-mcp

---

Architecture

┌─────────────────────────────┐
│      MCP Client             │
│   Claude / Cursor / AI      │
└──────────────┬──────────────┘
               │
               │ MCP / stdio
               ▼
┌─────────────────────────────┐
│       justrouting-mcp       │
│                             │
│  geocode   route            │
│  table     optimize         │
└──────────────┬──────────────┘
               │
               │ Official Go Client
               ▼
┌─────────────────────────────┐
│    api.justrouting.tech     │
└─────────────────────────────┘

The MCP server is intentionally thin.

It exposes JustRouting capabilities through MCP and uses the official JustRouting Go client for API communication.

---

Releases

Prebuilt binaries are published through GitHub Releases.

To create a release:

git tag v0.1.0
git push origin v0.1.0

GitHub Actions builds the binaries and publishes the release.

The one-line installer always installs the latest release.

---

Roadmap

The core routing capabilities are already available:

• Route calculation
• Geocoding
• Distance and travel-time matrix
• Vehicle routing optimization

Future improvements may include:

• Alternative routes
• Waypoints
• Streamable HTTP transport
• Remote MCP deployment

---

License

MIT