Overview - JustRouting Docs

JustRouting MCP

JustRouting MCP lets 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.

What you can do

Tool	What it does
`geocode`	Place or address → coordinates
`route`	Calculate one route
`table`	Compare travel times or distances between multiple locations
`optimize`	Assign jobs to vehicles and order their stops

The tools are designed around three simple tasks:

route — calculate
table — compare
optimize — decide

Installation

One-line installer

On macOS or Linux:

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

The installer downloads the latest prebuilt binary for your OS and architecture, verifies its checksum, and installs justrouting-mcp. To install a specific version:

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

No Go installation is required.

From source

If you have Go installed:

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

Requires Go 1.25+. Make sure justrouting-mcp is available in your PATH. Prebuilt binaries for supported platforms are also available from GitHub Releases.

Configuration

The server reads the JustRouting API key from the JUSTROUTING_API_KEY environment variable:

export JUSTROUTING_API_KEY="YOUR-API-KEY"

You can get an API key from JustRouting.

Which tool should I use?

Use the simplest tool that matches the user’s task:

User needs	Tool
Get coordinates for a place or address	`geocode`
Calculate one route	`route`
Compare multiple routes	`table`
Find the nearest driver, store, or facility	`table`
Assign jobs to vehicles	`optimize`
Determine the order of multiple stops	`optimize`

A simple rule:

One route → route
Many routes to compare → table
Many jobs to assign and order → optimize
Place name or address → geocode first

Tools

`route`

Calculate a route between two locations. Use this tool 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

Do not use it for comparing many origin-destination pairs. Use table instead. Do not use it for assigning jobs to vehicles or ordering multiple stops. Use optimize instead.

Input

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

Coordinates must use:

longitude,latitude

For example:

103.8198,1.3521

Motorcycle routing

profile is optional. Set it to "motorcycle" when the user explicitly asks for a motorcycle or motorbike route. Otherwise, omit profile to use the default driving profile.

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

Avoiding roads

Use exclude when the user explicitly asks to avoid a road type. Supported values:

toll
motorway
ferry

For example:

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

Road avoidance is a preference, not a guarantee. The 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 — route distance in meters
duration_seconds — estimated travel time in seconds
profile — routing profile used
geometry — simplified encoded polyline for the route
summary.roads — main roads used by the route
summary.tolls — whether the route uses toll roads
summary.ferry — 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 this tool 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"
  ]
}

Each coordinate has a stable zero-based index based on its position in the coordinates array. For example:

coordinates[0] → index 0
coordinates[1] → index 1
coordinates[2] → index 2

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]

means the travel time from coordinate 0 to coordinate 2. The response includes sources and destinations with the original coordinate indices so the matrix can be mapped back to the user’s locations.

Sources and destinations

Optional sources and destinations restrict the matrix to subsets of the 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.

duration — travel time in seconds
distance — distance in meters

Motorcycle routing

Set:

"profile": "motorcycle"

when the user explicitly asks for motorcycle or motorbike routing. Otherwise, omit profile.

Nearest-driver example

For a question such as:

Which driver is closest to the customer?

Keep the locations in a fixed order:

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

Then:

Use [0] as the source.
Use the driver indices as destinations.
Read the corresponding values from the first matrix row.
Ignore null values.
Choose the smallest distance or duration, depending on the user’s request.

For example:

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

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. If the user provides place names or addresses instead of coordinates, call geocode first for every place. Keep the locations in the same order when constructing the matrix request.

`geocode`

Search for a place or address and convert it into coordinates. Use this tool 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 in longitude,latitude format.

Structured input

The search is structured. Parse the user’s location into the fields that can be determined:

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

Only provide fields that are known from the user’s request. Do not invent or guess missing address components. For example:

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

When the user’s context provides a country or city, include it to disambiguate common, abbreviated, or misspelled place names.

Limit and filters

limit is optional and defaults to 1. The maximum value is 10. Use a larger limit when the location is ambiguous or the user asks for alternatives. filters can optionally restrict the search. For example:

{
  "name": "Marina Bay Sands",
  "country": "Singapore",
  "limit": 5,
  "filters": ["countrycode:sg"]
}

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. If 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. When using geocode as part of a routing workflow, verify that the selected result matches the user’s intended place before passing its coordinates to the next tool. If no result matches, the tool returns an error so the assistant can refine the search.

`optimize`

Assign jobs to vehicles and determine the order in which each vehicle should visit its assigned jobs. Use this tool when the user needs to:

assign multiple deliveries or pickups to vehicles
plan routes for a fleet
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 or travel times 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"
    }
  ]
}

Every vehicle must have a unique id. Every job must have a unique id and a location. Locations must use:

longitude,latitude

Each vehicle must have at least a start or an end. For a round trip, set both start and end 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.

Vehicle profiles

Each vehicle can use its own routing profile. Use:

"profile": "motorcycle"

when the user explicitly asks for a motorcycle or motorbike route. Otherwise, omit profile to use the default driving profile. For example:

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

Output

A simplified result looks like:

{
  "summary": {
    "cost": 2733,
    "routes": 2,
    "unassigned": 0,
    "duration": 2733
  },
  "routes": [
    {
      "vehicle": 1,
      "cost": 1144,
      "duration": 1144,
      "steps": [
        {
          "type": "start",
          "location": [103.7923, 1.3246],
          "arrival": 0
        },
        {
          "type": "job",
          "job": 2,
          "location": [103.7843, 1.3149],
          "arrival": 269,
          "duration": 269
        },
        {
          "type": "job",
          "job": 1,
          "location": [103.7975, 1.3104],
          "arrival": 673,
          "duration": 673
        },
        {
          "type": "end",
          "location": [103.7923, 1.3246],
          "arrival": 1144,
          "duration": 1144
        }
      ]
    }
  ],
  "unassigned": []
}

Use routes[].steps to determine:

which vehicle serves each job
the order in which jobs are visited
when each job is reached

A job step contains the job ID, arrival time, travel duration, and travel distance for reaching that job. Always check unassigned. Do not assume that every job will be assigned. 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?

Use:

geocode → geocode → route

Geocode the origin.
Geocode the destination.
Verify the selected results match the intended places.
Pass their coordinates values to route.

If the user already provides coordinates, skip geocoding.

Find the nearest driver

For:

Which driver is closest to this customer?

Use:

geocode × N → table

Geocode the customer.
Geocode each driver.
Keep the locations in a fixed order.
Put the customer in sources.
Put the drivers in destinations.
Compare the corresponding distance or duration values.
Ignore unreachable null values.

Plan multiple vehicles

For:

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

Use:

geocode × N → optimize

Geocode each vehicle’s start/end location.
Geocode every job location.
Create one vehicle entry per vehicle.
Create one job entry per customer.
Call optimize.
Read routes[].steps to determine each vehicle’s itinerary.
Check unassigned for jobs that could not be served.

Coordinate format

All routing tools use:

longitude,latitude

For example:

103.8198,1.3521

This means:

longitude = 103.8198
latitude  = 1.3521

Do not reverse the order.

Claude

Claude Code

Add JustRouting MCP with:

claude mcp add justrouting \
  --env JUSTROUTING_API_KEY=YOUR-API-KEY \
  -- justrouting-mcp

Claude Desktop

Add the server to claude_desktop_config.json:

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

Restart Claude Desktop after changing the configuration.

Cursor

Add JustRouting MCP from Settings → MCP → Add new MCP server. Use:

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

Once connected, Cursor can use the JustRouting tools directly.

​JustRouting MCP

​What you can do

​Installation

​One-line installer

​From source

​Configuration

​Which tool should I use?

​Tools

​route

​Input

​Motorcycle routing

​Avoiding roads

​Output

​table

​Input

​Sources and destinations

​Annotations

​Motorcycle routing

​Nearest-driver example

​Output

​geocode

​Structured input

​Limit and filters

​Output

​optimize

​Input

​Vehicle profiles

​Output

​Agent workflows

​Route between two places

​Find the nearest driver

​Plan multiple vehicles

​Coordinate format

​Claude

​Claude Code

​Claude Desktop

​Cursor

​Related

JustRouting MCP

What you can do

Installation

One-line installer

From source

Configuration

Which tool should I use?

Tools

`route`

Input

Motorcycle routing

Avoiding roads

Output

`table`

Input

Sources and destinations

Annotations

Motorcycle routing

Nearest-driver example

Output

`geocode`

Structured input

Limit and filters

Output

`optimize`

Input

Vehicle profiles

Output

Agent workflows

Route between two places

Find the nearest driver

Plan multiple vehicles

Coordinate format

Claude

Claude Code

Claude Desktop

Cursor

Related