# MapGO MCP Server

Give your AI assistant (Claude Desktop, Claude Code, Cursor, …) live geospatial tools
powered by [MapGO](https://mapgo.io):

| Tool | What it answers |
|---|---|
| `mapgo_location_hierarchy` | "What country/region/municipality is this coordinate in?" |
| `mapgo_border_distance` | "How far is this point from the nearest country border?" |
| `mapgo_coastline_distance` | "How far is this point from the sea?" |
| `mapgo_point_distance` | "How far apart are these two points, and in which direction?" |

All coordinates are decimal degrees (latitude −90..90, longitude −180..180).

## Requirements

- A MapGO account on a **paid plan** — tool calls count against your monthly request quota.
- An API key: go to [mapgo.io/dashboard/api-keys](https://mapgo.io/dashboard/api-keys),
  click **Generate**, and copy the `mapgo_sk_...` key (it is shown only once).

## Install in Claude Desktop — one file, no terminal (recommended)

The easiest way. No Node install, no config files, no command line — Claude Desktop
runs everything for you.

1. Download **`mapgo.mcpb`** (from mapgo.io, or from this repo).
2. Open **Claude Desktop** → the **☰** menu → **Settings → Extensions**.
3. **Drag `mapgo.mcpb` onto the Extensions page** (or double-click the file).
4. When prompted, paste your **MapGO API Key** (`mapgo_sk_...`) into the box and click
   install / enable.
5. Ask Claude a location question — e.g. *"How far is Paris from the coastline?"*

That's it. The key is stored securely by your operating system; everything else is
bundled inside the file.

---

The options below are for developer tools (Claude Code, Cursor) or for running from
source. Most users only need the one-file install above.

### Requirements for the developer / source options

- Node.js 18 or newer.

## Install — run from source

Until the npm package is published, clone and build this repo once:

```bash
git clone https://github.com/Nomit83/mapgo_mcp.git
cd mapgo_mcp
npm install
npm run build
```

Then use `node /full/path/to/mapgo_mcp/dist/index.js` as the server command in the
configs below (in place of `npx -y @mapgo/mcp-server`). For example, for Claude Code:

```bash
claude mcp add mapgo --env MAPGO_API_KEY=mapgo_sk_YOUR_KEY_HERE -- node /full/path/to/mapgo_mcp/dist/index.js
```

## Claude Desktop

Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config),
then restart Claude Desktop:

```json
{
  "mcpServers": {
    "mapgo": {
      "command": "npx",
      "args": ["-y", "@mapgo/mcp-server"],
      "env": { "MAPGO_API_KEY": "mapgo_sk_YOUR_KEY_HERE" }
    }
  }
}
```

## Claude Code

```bash
claude mcp add mapgo --env MAPGO_API_KEY=mapgo_sk_YOUR_KEY_HERE -- npx -y @mapgo/mcp-server
```

## Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "mapgo": {
      "command": "npx",
      "args": ["-y", "@mapgo/mcp-server"],
      "env": { "MAPGO_API_KEY": "mapgo_sk_YOUR_KEY_HERE" }
    }
  }
}
```

## Try it

Ask your assistant:

> "How far is Kraków from the coast, and which country border is nearest?"

## Troubleshooting

- **"Invalid or missing MapGO API key"** — re-check the key in your config; generate a
  new one at [mapgo.io/dashboard/api-keys](https://mapgo.io/dashboard/api-keys) if lost.
- **"requires a paid plan"** — API access (including MCP) is for paid plans.
- **"Monthly MapGO quota exceeded"** — each tool call uses 1 request from your plan's
  monthly quota; it resets on the 1st of the month.

## Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `MAPGO_API_KEY` | yes | — | Your `mapgo_sk_...` API key |
| `MAPGO_API_BASE` | no | `https://mapgo.io` | Override for local testing (`http://localhost:3000`) |