# geopera-mcp

The official [Model Context Protocol](https://modelcontextprotocol.io) server for the
[Geopera](https://geopera.com) geospatial data platform. It exposes Geopera operations
as MCP tools so an AI agent (Claude Desktop, Claude Code, or your own MCP client) can
discover imagery, place and read back orders, run analytics, and more — with the same
auth, scopes, and provenance as any other Geopera client.

Each tool is named after its operation id (e.g. `orders.archive.place`) and proxies the
call to `POST /v1/op/{operation_id}`. The server imports nothing from the backend; it is
a standalone client of the same typed surface the Python/TypeScript SDKs and CLI consume.

## Install

```bash
pip install geopera-mcp
```

This installs the `geopera-mcp` console command, which speaks the `stdio` transport that
MCP clients attach to. Requires Python 3.11+.

## Run

The server is configured through environment variables. At minimum:

```bash
export GEOPERA_API_URL="https://api.geopera.com"
export GEOPERA_API_TOKEN="gpra_..."   # a Geopera API key, or a session token
geopera-mcp
```

`geopera-mcp` runs over stdio by default — your MCP client launches it as a subprocess.
Set `MCP_TRANSPORT=http` to serve the streamable-HTTP transport instead (for a hosted
deployment).

## Wire it into an MCP client

Add a `geopera` entry under `mcpServers`. For Claude Desktop
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "geopera": {
      "command": "geopera-mcp",
      "env": {
        "GEOPERA_API_URL": "https://api.geopera.com",
        "GEOPERA_API_TOKEN": "gpra_your_api_key"
      }
    }
  }
}
```

Restart the client and the Geopera tools appear. The agent's reach is exactly the scopes
on the token — it can do nothing the token could not do directly.

## Environment variables

| Variable | Purpose |
| --- | --- |
| `GEOPERA_API_URL` | Geopera API base URL. Default `https://api.geopera.com`. |
| `GEOPERA_API_TOKEN` | A `gpra_` API key or a session token, sent upstream as `Authorization: Bearer`. |
| `MCP_TRANSPORT` | `stdio` (default) or `http`. |
| `PORT` | Port for the `http` transport. |

## Documentation

Full docs: [docs.geopera.com/api-reference/sdks/mcp](https://docs.geopera.com/api-reference/sdks/mcp).

## License

MIT