Geowire MCP Server

GeoWire

Add real-world places to any AI agent in 5 minutes — no API key required.

One place-search interface for every AI and map provider.

GeoWire is an open-source geo search gateway that sits between AI agents and map/place data providers (OpenStreetMap, Google, your own data) and exposes them through a single MCP server, REST API, and SDK — with provider fallback, multi-provider merge + dedup, cost budgets, and a policy engine that enforces each provider's caching/attribution terms.

Status: v0.1 ("It works") — published on npm. MCP · REST · CLI · SDK all functional.

Why GeoWire?

Quickstart

1. MCP (Claude Desktop / Cursor) — 30 seconds

Add this to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "geowire": { "command": "npx", "args": ["-y", "@geowirehq/mcp"] }
  }
}

Then ask: "Find a 24-hour pharmacy near District 1, Ho Chi Minh City." Works with zero API keys — OpenStreetMap is the default provider. Add "env": { "GOOGLE_MAPS_API_KEY": "..." } to enable Google.

2. CLI — one-shot search & server

npx @geowirehq/cli search "Eiffel Tower"          # terminal search with a results table
npx @geowirehq/cli search "coffee" --near 37.4979,127.0276   # bias to a coordinate
npx @geowirehq/cli                                # start the REST + MCP server (zero-config)
npx @geowirehq/cli init                           # interactive setup wizard (.env + config)
npx @geowirehq/cli test                           # check provider connections

3. Docker — self-hosted server

docker run -p 4980:4980 geowire/geowire
# then:
curl -X POST http://localhost:4980/v1/places/search \
  -H 'content-type: application/json' \
  -d '{"query":"pharmacy","near":{"latitude":10.7769,"longitude":106.7009}}'

Or with docker compose up (see docker-compose.yml). API docs at /docs.

4. SDK (embedded)

import { createGeoWire } from "@geowirehq/core";
import { createNominatimProvider } from "@geowirehq/provider-nominatim";

const geo = createGeoWire({ providers: [createNominatimProvider()] });
const { results, meta } = await geo.searchPlaces({
  query: "coffee",
  near: { latitude: 37.5, longitude: 127.0 },
});

MCP tools

Every response includes both a human-readable summary and structuredContent (schema-valid JSON).

REST endpoints

Optional Bearer auth: set GEOWIRE_API_KEYS=key1,key2.

Configuration (optional — everything works without it)

geowire.config.yaml:

providers:
  nominatim: { enabled: true }                       # default ON, no key
  google:    { enabled: true, apiKey: ${GOOGLE_MAPS_API_KEY} }
  internal:  { enabled: true, source: ./my-places.csv, priority: 100 }
routing:
  defaultStrategy: merge          # first-success | merge
budget:
  perRequestMaxUSD: 0.10          # over-budget paid providers are skipped, free ones used

Keys come from the environment (${VAR}), never committed in plaintext.

Providers

Want another provider? See CONTRIBUTING.md — "Write a provider in 30 minutes".

Architecture

AI agent / app
   │  MCP · REST · SDK
   ▼
GeoWire core  ── pipeline: plan → execute → normalize → dedup → rank → policy → cache
   │  GeoProvider contract
   ▼
providers: nominatim · google · internal · (community)

Monorepo packages: schema · provider-sdk · provider-testkit · core · providers/* · mcp · apps/server · cli.

Documentation

• System design
• Implementation plan
• Contributing + write a provider
• Examples: examples/

License

Apache-2.0. GeoWire's code license is separate from the terms of third-party map/place data providers — usage of Google, Mapbox, HERE, Kakao, Naver, etc. is governed by each provider's own terms. OSM data is under ODbL; GeoWire's policy engine enforces attribution and caching limits per provider.