> ## Documentation Index
> Fetch the complete documentation index at: https://docs.justrouting.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Give AI assistants access to JustRouting's routing, geocoding, distance matrix, and vehicle routing capabilities.

## JustRouting MCP

JustRouting MCP lets AI assistants such as Claude and Cursor use [JustRouting](https://justrouting.tech/) 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://github.com/justrouting/mcp/releases).

## Configuration

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

```bash theme={null}
export JUSTROUTING_API_KEY="YOUR-API-KEY"
```

You can get an API key from [JustRouting](https://justrouting.tech/).

## 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

```json theme={null}
{
  "origin": "103.8198,1.3521",
  "destination": "103.9915,1.3644"
}
```

Coordinates must use:

```text theme={null}
longitude,latitude
```

For example:

```text theme={null}
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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```text theme={null}
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:

```text theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
"annotations": ["duration"]
```

for travel times.

Use:

```json theme={null}
"annotations": ["distance"]
```

for distances.

Use:

```json theme={null}
"annotations": ["duration", "distance"]
```

for both.

If omitted, both are returned.

* `duration` — travel time in seconds
* `distance` — distance in meters

#### Motorcycle routing

Set:

```json theme={null}
"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:

```text theme={null}
coordinates[0] = customer
coordinates[1] = driver A
coordinates[2] = driver B
coordinates[3] = driver C
```

Then:

1. Use `[0]` as the source.
2. Use the driver indices as destinations.
3. Read the corresponding values from the first matrix row.
4. Ignore `null` values.
5. Choose the smallest distance or duration, depending on the user's request.

For example:

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

#### Output

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "name": "Marina Bay Sands",
  "country": "Singapore",
  "limit": 5,
  "filters": ["countrycode:sg"]
}
```

#### Output

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```text theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
"profile": "motorcycle"
```

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

Otherwise, omit `profile` to use the default driving profile.

For example:

```json theme={null}
{
  "id": 1,
  "profile": "motorcycle",
  "start": "103.7923,1.3246",
  "end": "103.7923,1.3246"
}
```

#### Output

A simplified result looks like:

```json theme={null}
{
  "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:

```text theme={null}
geocode → geocode → route
```

1. Geocode the origin.
2. Geocode the destination.
3. Verify the selected results match the intended places.
4. 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:

```text theme={null}
geocode × N → table
```

1. Geocode the customer.
2. Geocode each driver.
3. Keep the locations in a fixed order.
4. Put the customer in `sources`.
5. Put the drivers in `destinations`.
6. Compare the corresponding distance or duration values.
7. 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:

```text theme={null}
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:

```text theme={null}
longitude,latitude
```

For example:

```text theme={null}
103.8198,1.3521
```

This means:

```text theme={null}
longitude = 103.8198
latitude  = 1.3521
```

Do not reverse the order.

***

## Claude

### Claude Code

Add JustRouting MCP with:

```bash theme={null}
claude mcp add justrouting \
  --env JUSTROUTING_API_KEY=YOUR-API-KEY \
  -- justrouting-mcp
```

### Claude Desktop

Add the server to `claude_desktop_config.json`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "mcpServers": {
    "justrouting": {
      "command": "justrouting-mcp",
      "env": {
        "JUSTROUTING_API_KEY": "your-api-key"
      }
    }
  }
}
```

Once connected, Cursor can use the JustRouting tools directly.

***

## Related

* [Quickstart](https://docs.justrouting.tech/quickstart)
* [Authentication](https://docs.justrouting.tech/guides/authentication)
* [Geocode API](https://docs.justrouting.tech/api/geocode)
* [Directions API](https://docs.justrouting.tech/api/directions)
* [Distance Matrix API](https://docs.justrouting.tech/api/matrix)
* [Fleet Optimization API](https://docs.justrouting.tech/api/optimization)
* [SDKs](https://docs.justrouting.tech/sdks)
* [JustRouting MCP on GitHub](https://github.com/justrouting/mcp)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.