# Use Mapit with AI

Two ways to use Mapit with AI: ask an assistant about your own bike, or have a coding agent write the code that reads it.

> **Beta, free for now.** My Mapit and the service behind it are a beta: they may change or stop, they come with no uptime promise, and Mapit does not charge for them today. Do not rely on them for emergencies or to recover a stolen bike: use the Mapit app. See the [beta terms](https://developers.mapit.me/terms.md).

## Ask an assistant about your bike

**My Mapit** (Mi Mapit in Spanish) connects an AI assistant to your own Mapit account. Ask “Where is my bike?”, “What rides did I do yesterday?” or “When does my subscription end?”. You sign in with your Mapit account on Mapit's page, and you choose what the assistant may see. It never gets your password.

### Plugin or connector

My Mapit comes two ways. The **plugin** bundles the My Mapit connector with two skills. The marketplace `mapit-iot/ai-plugin` (a GitHub repository) is added in Claude Code and Codex below. In claude.ai an organization admin adds it under Organization settings > Plugins & skills > Marketplaces, from a private copy (see claude.ai below). If your assistant has no plugins, add the **connector** by its URL instead, as for claude.ai and ChatGPT below.

### claude.ai

In Settings, open Connectors and add a custom connector named **My Mapit** with the URL `https://api.mapit.me/mcp`. Then connect it and sign in with your Mapit account.

**Team and Enterprise owners** can give the plugin to the whole organization: in Organization settings, open Plugins & skills, then Marketplaces, and add the GitHub repository that holds a copy of `mapit-iot/ai-plugin`. Anthropic accepts only private or internal repositories there, so copy it into a private repository of the organization first. Everyone else adds the connector as above.

### ChatGPT

Add a custom connector (an app that uses MCP) named **My Mapit** with the URL `https://api.mapit.me/mcp`, and sign in with your Mapit account. Where custom connectors are in ChatGPT depends on your plan and app version.

### Claude Code

Install the Mapit plugin from the [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin) marketplace:

```
/plugin marketplace add mapit-iot/ai-plugin
/plugin install mapit@mapit
```

Then run `/mcp`, choose **plugin:mapit:my-mapit** and sign in. The plugin also adds two skills that help the assistant answer questions about your bike and build ride totals.

### OpenAI Codex

Install the plugin from the same [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin) marketplace:

```
codex plugin marketplace add mapit-iot/ai-plugin
codex plugin add mapit@mapit
```

Then sign in with your Mapit account the first time you use it.

### Any other MCP client

Add a remote MCP server with the URL `https://api.mapit.me/mcp`. It uses the Streamable HTTP transport and OAuth sign-in: the client opens Mapit's sign-in page, you approve it, and it keeps a token, never your password.

```
https://api.mapit.me/mcp
```

### What the assistant can and cannot do

- **Read-only.** It can read your account, vehicles, subscription, where each vehicle last reported, and your routes and ride statistics. It cannot change anything, and it cannot send commands to your bike.
- **Location and routes need your tick.** On the sign-in page you choose whether to share location and route history. If you leave them unticked, the assistant cannot see them.
- **Last reported, not live.** A position is what the tracker last sent, and the assistant says when. It cannot follow your bike live.
- **Your account only.** It sees your vehicles, as the Mapit app shows them.
- **You stay in control.** See and end every connection at [login.mapit.me/connections](https://login.mapit.me/connections). It takes effect on the next request.

Claude, ChatGPT and other assistants connected this way are on the [Approved apps](https://developers.mapit.me/approved-apps.md) list. Use is for your own personal, non-commercial purposes, under the [API terms of use](https://developers.mapit.me/terms.md) and the [API privacy notice](https://developers.mapit.me/privacy.md).

## Build with an AI coding agent

Give your coding agent these addresses. Each docs page is also available as Markdown: add `.md` to its address.

- [`https://developers.mapit.me/llms.txt`](https://developers.mapit.me/llms.txt): an index of every page, with a line on each.
- [`https://developers.mapit.me/llms-full.txt`](https://developers.mapit.me/llms-full.txt): all the docs in one Markdown file.
- [`https://developers.mapit.me/openapi.json`](https://developers.mapit.me/openapi.json): the OpenAPI description, with every endpoint, parameter and field.

### Instructions for the agent

Paste this into your agent's instructions (for example `AGENTS.md` or `CLAUDE.md`) or at the start of a task:

```
You are writing code against the Mapit API (beta).
Docs index: https://developers.mapit.me/llms.txt
All docs in one file: https://developers.mapit.me/llms-full.txt
OpenAPI spec: https://developers.mapit.me/openapi.json

- Base URL: https://api.mapit.me/v1
- Auth: send a personal key as "Authorization: Bearer $MAPIT_KEY". Read the key
  from an environment variable. Never hard-code it, print it or log it.
- Rate limit: 30 requests a minute per key or access token, for the REST API and the MCP connector. Bursts above it may be tolerated, never rely on them. On 429, wait Retry-After seconds.
  Poll /status at most once a minute. See https://developers.mapit.me/limits.md
- Every 200 answer has an ETag: send it back in If-None-Match. 304 means
  nothing changed.
- Version 1 only gains fields: ignore fields you do not know.
- Ids and cursors are opaque: store them, never build or parse them.
  Follow nextCursor until it is null.
- Positions are last reported, not live: show when (lastLocationAt).
- Location and routes need permission on the key: 403 means it lacks it.
- Read-only, except disconnecting apps and keys. Never call DELETE unless
  the user asks.
- Personal, non-commercial use: the user's own vehicles only.
- Python: use the aiomapit package instead of raw HTTP.
```

### Python: aiomapit

For Python, the fastest path is [aiomapit](https://pypi.org/project/aiomapit/), Mapit's official async client (Python 3.12 or newer). It is typed, handles paging and is what the [Home Assistant](https://developers.mapit.me/home-assistant.md) integration uses. Create a [personal key](https://developers.mapit.me/keys.md) first.

```
pip install aiomapit
```

```
import asyncio, os
from aiomapit import MapitClient

async def main():
    async with MapitClient(os.environ["MAPIT_KEY"]) as client:
        async for status in client.iter_statuses():
            if status.state:
                print(status.vehicle_id, status.state.latitude, status.state.longitude)

asyncio.run(main())
```

Other languages can use [the reference](https://developers.mapit.me/reference.md) or the OpenAPI file to generate a client.
