# Polarsteps MCP tools

> Every Polarsteps MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/polarsteps

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

14 tools for Polarsteps on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Polarsteps account
- Integration page: https://cotlet.dev/integrations/polarsteps-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `polarsteps_list_trips` | read | Your trips, newest first, with dates, privacy level, distance and step count. |
| `polarsteps_get_trip` | read | One trip: name, summary, dates, privacy, Travel Buddies, distance and countries. |
| `polarsteps_list_steps` | read | Steps of a trip in order, with place, country, date, title and photo count. |
| `polarsteps_get_step` | read | Full step: story text, place and coordinates, date, photo and video links. |
| `polarsteps_list_step_comments` | read | Comments your followers left on a step, with author and date. |
| `polarsteps_get_travel_stats` | read | Countries visited, total kilometers, number of trips and steps on your profile. |
| `polarsteps_export_trip` | read | One trip as a download link, valid for 1 hour: route, steps and photo links. |
| `polarsteps_create_trip` | write | New trip, past or upcoming, with the privacy level you pick. |
| `polarsteps_add_step` | write | Add a step to a trip with a story and photos. People who can see the trip see it. |
| `polarsteps_import_steps` | write | Add many steps at once, e.g. a past trip from a CSV, sorted by date. |
| `polarsteps_update_step` | write | Change the title, story, place or date of a step. |
| `polarsteps_add_step_photos` | write | Add photos or videos to an existing step. |
| `polarsteps_reply_to_step_comment` | write | Reply to a follower comment on one of your steps, as you. |
| `polarsteps_set_trip_privacy` | write | Choose who can see a trip: only you, your followers or everyone. |

## List trips

MCP tool: `polarsteps_list_trips`

Access: read.

Returns the trips on your own account, newest first. Filter by status to see only planned, ongoing or past trips. Use trip_id from each item in the other endpoints.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | all, planned, ongoing or past. Default: all. |
| `limit` | integer | no | 1 to 100. Default: 50. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_list_trips",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "trips": [
      {
        "trip_id": "18452237",
        "name": "Portugal by train",
        "start_date": "2026-10-01",
        "end_date": null,
        "privacy": "followers",
        "steps": 9,
        "distance_km": 612
      },
      {
        "trip_id": "16720458",
        "name": "Patagonia",
        "start_date": "2025-12-04",
        "end_date": "2026-01-19",
        "privacy": "everyone",
        "steps": 41,
        "distance_km": 3870
      }
    ]
  },
  "isError": false
}
```

## Get trip

MCP tool: `polarsteps_get_trip`

Access: read.

Returns one trip with its summary, start and end dates, privacy level and the Travel Buddies on it. Trip dates are separate from the dates of its steps.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_get_trip",
    "arguments": {
      "trip_id": "trip_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "trip_id": "18452237",
    "name": "Portugal by train",
    "summary": "Two weeks from Porto to Faro on regional trains.",
    "start_date": "2026-10-01",
    "end_date": null,
    "privacy": "followers",
    "travel_buddies": [
      "Marta Silva"
    ],
    "distance_km": 612,
    "countries": [
      "Portugal"
    ]
  },
  "isError": false
}
```

## List steps

MCP tool: `polarsteps_list_steps`

Access: read.

Lists the steps of one trip in the order of the trip. Story is a short preview; get_step returns the full text, coordinates and photo links. Pass since to see only steps from a given date.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `since` | date | no | Only steps on or after this date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_list_steps",
    "arguments": {
      "trip_id": "trip_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "steps": [
      {
        "step_id": "231908554",
        "title": "Fado night in Alfama",
        "place": "Lisbon",
        "country": "Portugal",
        "date": "2026-10-09T19:30:00+01:00",
        "photos": 2,
        "comments": 1
      },
      {
        "step_id": "231544107",
        "title": "Tram 28 to Graça",
        "place": "Lisbon",
        "country": "Portugal",
        "date": "2026-10-09T11:10:00+01:00",
        "photos": 3,
        "comments": 0
      }
    ]
  },
  "isError": false
}
```

## Get step

MCP tool: `polarsteps_get_step`

Access: read.

Returns one step with its full story, the place and its coordinates, the date and time, and links to every photo and video. Use it before editing a step or turning it into a post.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_get_step",
    "arguments": {
      "step_id": "231908554"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "step_id": "231908554",
    "trip_id": "18452237",
    "title": "Fado night in Alfama",
    "story": "Got lost in the old town, then found a tiny fado bar with six tables.",
    "place": "Alfama, Lisbon, Portugal",
    "coordinates": {
      "lat": 38.711,
      "lon": -9.1304
    },
    "date": "2026-10-09T19:30:00+01:00",
    "media": [
      "https://example.com/photos/alfama-1.jpg",
      "https://example.com/photos/alfama-2.jpg"
    ]
  },
  "isError": false
}
```

## List step comments

MCP tool: `polarsteps_list_step_comments`

Access: read.

Returns the comments on one step, oldest first, with author and date. Replies from you are included under the comment they answer. Use comment_id with reply_to_step_comment.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_list_step_comments",
    "arguments": {
      "step_id": "step_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "comments": [
      {
        "comment_id": "cm_4821",
        "author": "Eva Novak",
        "body": "That fado bar looks amazing!",
        "created_at": "2026-10-09T21:05:00+01:00",
        "replies": []
      }
    ]
  },
  "isError": false
}
```

## Get travel stats

MCP tool: `polarsteps_get_travel_stats`

Access: read.

Returns the figures from the Travel stats on your profile: countries visited, kilometers, trips and steps. Countries are counted from the steps you add.

### Parameters

No parameters.

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_get_travel_stats",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "countries": 14,
    "distance_km": 28640,
    "trips": 6,
    "steps": 187
  },
  "isError": false
}
```

## Export trip

MCP tool: `polarsteps_export_trip`

Access: read.

Exports one trip as json, gpx or markdown and returns a download link valid for 1 hour. gpx holds the route, markdown holds the step stories. Set include_media for a zip of the full-size photos and videos. It only reads, so it never asks for your OK.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `format` | enum | no | json, gpx or markdown. Default: json. |
| `include_media` | boolean | no | Add a zip of full-size photos and videos. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_export_trip",
    "arguments": {
      "trip_id": "16720458",
      "format": "gpx",
      "include_media": false
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "trip_id": "16720458",
    "format": "gpx",
    "download_url": "https://example.com/exports/16720458.gpx",
    "expires_at": "2026-10-11T15:00:00+02:00",
    "steps": 41
  },
  "isError": false
}
```

## Create trip

MCP tool: `polarsteps_create_trip`

Access: write. Confirm: waits for the user's OK before it runs.

Creates a trip with a name and start date. The start date can be in the past, for a trip from before you used Polarsteps. Privacy is Only me (only_me) unless you set followers or everyone, so nothing is shared by accident. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Trip name. |
| `start_date` | date | yes | First day of the trip. Can be in the past. |
| `end_date` | date | no | Last day. Leave empty for an ongoing trip. |
| `summary` | string | no | Short trip description. |
| `privacy` | enum | no | only_me, followers or everyone. Default: only_me. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_create_trip",
    "arguments": {
      "name": "Jane Doe",
      "start_date": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "trip_id": "20931176",
    "name": "Vietnam 2019",
    "start_date": "2019-03-02",
    "end_date": "2019-03-20",
    "privacy": "only_me",
    "steps": 0
  },
  "isError": false
}
```

## Add step

MCP tool: `polarsteps_add_step`

Access: write. Confirm: waits for the user's OK before it runs.

Adds one step to a trip at a place and time, with an optional title, story and photos by URL. The date and place set where the step sits on the route. Everyone who can see the trip, by its privacy level, sees the step. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `place` | string | yes | Place name or "lat,lon". |
| `date` | datetime | yes | ISO 8601 with time zone. |
| `title` | string | no | Step title. Default: the place name. |
| `story` | string | no | Step text. |
| `photo_urls` | string[] | no | Photo or video URLs to attach. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_add_step",
    "arguments": {
      "trip_id": "18452237",
      "place": "Alfama, Lisbon, Portugal",
      "date": "2026-10-09T19:30:00+01:00",
      "title": "Fado night in Alfama",
      "story": "Got lost in the old town, then found a tiny fado bar with six tables.",
      "photo_urls": [
        "https://example.com/photos/alfama-1.jpg",
        "https://example.com/photos/alfama-2.jpg"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "step_id": "231908554",
    "trip_id": "18452237",
    "title": "Fado night in Alfama",
    "place": "Lisbon, Portugal",
    "date": "2026-10-09T19:30:00+01:00",
    "photos": 2
  },
  "isError": false
}
```

## Import steps

MCP tool: `polarsteps_import_steps`

Access: write. Confirm: waits for the user's OK before it runs.

Adds up to 50 steps to one trip in a single call and sorts them by date, so the route draws in travel order. Each step needs a place and a date. The OK covers the whole batch. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `steps` | object[] | yes | Up to 50 items of { place, date, title, story, photo_urls }. place and date are required. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_import_steps",
    "arguments": {
      "trip_id": "20931176",
      "steps": [
        {
          "place": "Hanoi, Vietnam",
          "date": "2019-03-02T09:00:00+07:00",
          "title": "Arrival in Hanoi"
        },
        {
          "place": "Ha Long Bay, Vietnam",
          "date": "2019-03-05T08:00:00+07:00",
          "title": "Boat to Ha Long Bay"
        }
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "trip_id": "20931176",
    "added": 2,
    "steps": [
      {
        "step_id": "301440018",
        "title": "Arrival in Hanoi",
        "date": "2019-03-02T09:00:00+07:00"
      },
      {
        "step_id": "301440019",
        "title": "Boat to Ha Long Bay",
        "date": "2019-03-05T08:00:00+07:00"
      }
    ]
  },
  "isError": false
}
```

## Update step

MCP tool: `polarsteps_update_step`

Access: write. Confirm: waits for the user's OK before it runs.

Changes the fields you send and leaves the rest of the step as it is. Changing the place or date moves the step on the route. Trip start and end dates are not changed. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |
| `fields` | object | yes | Any of title, story, place, date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_update_step",
    "arguments": {
      "step_id": "231908554",
      "fields": {
        "story": "Got lost in the old town, then found a tiny fado bar with six tables."
      }
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "step_id": "231908554",
    "updated": [
      "story"
    ],
    "date": "2026-10-09T19:30:00+01:00"
  },
  "isError": false
}
```

## Add step photos

MCP tool: `polarsteps_add_step_photos`

Access: write. Confirm: waits for the user's OK before it runs.

Attaches photos or videos by URL to a step that already exists. People who can see the trip see them. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |
| `photo_urls` | string[] | yes | Photo or video URLs. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_add_step_photos",
    "arguments": {
      "step_id": "step_8c41d2",
      "photo_urls": [
        "https://example.com"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "step_id": "231908554",
    "added": 2,
    "photos_total": 4
  },
  "isError": false
}
```

## Reply to step comment

MCP tool: `polarsteps_reply_to_step_comment`

Access: write. Confirm: waits for the user's OK before it runs.

Adds a reply under a comment on your step. The reply appears under your name for people who can see the trip. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |
| `comment_id` | string | yes | Comment ID from list_step_comments. |
| `body` | string | yes | Reply text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_reply_to_step_comment",
    "arguments": {
      "step_id": "step_8c41d2",
      "comment_id": "comment_8c41d2",
      "body": "body"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "comment_id": "cm_4822",
    "parent_comment_id": "cm_4821",
    "step_id": "231908554",
    "status": "published"
  },
  "isError": false
}
```

## Set trip privacy

MCP tool: `polarsteps_set_trip_privacy`

Access: write. Confirm: waits for the user's OK before it runs.

Sets the privacy level of one trip to Only me, Followers or Everyone. It applies to the trip with all its steps. Followers can also see the trip through the secret link. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `privacy` | enum | yes | only_me, followers or everyone. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polarsteps_set_trip_privacy",
    "arguments": {
      "trip_id": "trip_8c41d2",
      "privacy": "only_me"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "trip_id": "18452237",
    "privacy": "everyone"
  },
  "isError": false
}
```