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

# MCP

> Give Claude, Cursor, and other MCP-compatible AI assistants road routing and geocoding with the JustRouting MCP server.

The JustRouting MCP server lets MCP-compatible AI assistants — Claude, Cursor, and others — calculate routes and geocode places directly. It exposes two tools:

* **`route`** — distance and travel duration between two locations, driving or motorcycle
* **`geocode`** — convert a place name or address into coordinates, ready to feed into `route`

The server is a thin stdio process built on the official JustRouting Go client, so authentication, retries, and rate-limit handling are inherited from the API. Source code and releases are on [GitHub](https://github.com/justrouting/mcp).

## Installation

### One-line installer (macOS / Linux)

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/justrouting/mcp/main/install.sh | sh
```

Downloads the latest prebuilt binary for your OS/architecture, verifies its checksum, and installs it to `/usr/local/bin` (or `~/.local/bin`). No Go required. Pin a specific version:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/justrouting/mcp/main/install.sh | JUSTROUTING_MCP_VERSION=v0.1.1 sh
```

### From source (Go users)

```bash theme={null}
go install github.com/justrouting/mcp/cmd/justrouting-mcp@latest
```

Requires Go 1.25+. Make sure `justrouting-mcp` is on your `PATH`. Prebuilt binaries for macOS, Linux, and Windows are also attached to every [release](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"
```

See [Authentication](/authentication) for creating an API key.

## Tools

### route

Calculate a route between two locations — driving by default, or motorcycle when requested.

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

`profile` is optional: set it to `"motorcycle"` for a motorcycle route, or omit it (or use `"car"`) for the default driving route. When the user mentions a motorcycle or motorbike, the assistant sets `profile` to `"motorcycle"`.

Coordinates use `longitude,latitude` order. If the user asks about places by name or address instead of coordinates, call `geocode` first and pass its `coordinates` values here.

```json theme={null}
{
  "distance_meters": 18500,
  "duration_seconds": 1500
}
```

* `distance_meters` — driving distance in **meters**
* `duration_seconds` — estimated travel time in **seconds**

### geocode

Search for places and convert a place name or address into coordinates. Use this before `route` when the user refers to places by name.

The search is structured: the assistant parses the user's place reference into address components and passes only the ones it can determine — `name`, `housenumber`, `street`, `postcode`, `city`, `country`. Prefer including `country` (and `city`) when the context implies them — they are the strongest disambiguators for common, abbreviated, or misspelled names.

```json theme={null}
{
  "name": "Marina Bay Sands",
  "housenumber": "10",
  "street": "Bayfront Avenue",
  "postcode": "018956",
  "city": "Singapore",
  "country": "Singapore"
}
```

At least one component is required. `limit` is optional and defaults to 1 (best match only); it must not exceed 10. `filters` is also optional, for example `"filters": ["countrycode:sg"]` to restrict results to Singapore.

```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 best first. The `coordinates` field is ready to pass to `route`. If nothing matches, the tool returns an error.

### Asking about places by name

For a prompt such as "how long from 'marina bay singapore' driving to 'changqi airport'?", the assistant geocodes each place and then routes:

1. `geocode` with `"name": "marina bay", "country": "singapore"` → take `coordinates`
2. `geocode` with `"name": "changqi airport"` → take `coordinates`
3. `route` with the two `coordinates` values as `origin` and `destination` (omit `profile` for driving)

## Claude

Claude Code (CLI):

```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"
      }
    }
  }
}
```

## Cursor

Add the MCP server with the same JSON configuration (Settings → MCP → Add new MCP server):

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

## Related

* [Quickstart](/quickstart)
* [Authentication](/authentication)
* [Geocode API](/api-reference/geocode)
* [Directions API](/api-reference/directions)
* [SDKs](/guides/sdks)