# geo-coding-mcp

An MCP server for forward geocoding via the [Nominatim](https://nominatim.openstreetmap.org/) API (OpenStreetMap). No API key required.

## Usage

### Claude CLI

```bash
claude mcp add --scope user geocoding -- npx -y geo-coding-mcp
```

### Manual configuration

Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "geocoding": {
      "command": "npx",
      "args": ["-y", "geo-coding-mcp"]
    }
  }
}
```

## Tool

### `geocode`

Forward geocodes a free-form location query and returns matching places with coordinates and address details.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | yes | Free-form search query, e.g. `"221B Baker Street, London"` |
| `limit` | number | no | Max results to return (1–40, default `5`) |
| `countrycodes` | string | no | Comma-separated ISO 3166-1 alpha-2 codes to filter by, e.g. `"gb,us"` |
| `addressdetails` | boolean | no | Include structured address breakdown (default `true`) |
| `viewbox` | string | no | Bounding box to boost results: `"x1,y1,x2,y2"` (min_lon,min_lat,max_lon,max_lat) |
| `bounded` | boolean | no | Restrict results to within the viewbox (requires `viewbox`) |

**Example response:**

```
Geocoding results for: Big Ben, London
Found 3 result(s)
==================================================

[1] Big Ben, Westminster Bridge Road, Lambeth, London, Greater London, England, SE1 7PB, United Kingdom
    Lat: 51.5007325  Lon: -0.1246254
    Type: tourism/attraction  (importance: 0.7654)
    Address: tourism: Big Ben, road: Westminster Bridge Road, city: London, postcode: SE1 7PB, country: United Kingdom
...
```

## Testing locally

```bash
npm run build
npx @modelcontextprotocol/inspector node ./build/index.js
```

## License

MIT