mapsql-mcp

mapsql-mcp

Ask your PostGIS or Oracle Spatial database questions in plain English and get the answer back as a map.

mapsql-mcp is a Model Context Protocol server that lets AI assistants (Claude Desktop, Claude Code, Cursor, and any other MCP client) explore, query and analyse a PostGIS or an Oracle Spatial (SDO_GEOMETRY) database *safely* and answer with maps rendered right in the chat.

*"Which pharmacies are within 500 m of Kızılay square?"* - the model discovers the layers, calls

within_distance (geodesic metres, whatever the table's SRID), then render_map. The picture above is the

literal output of those two tool calls on the bundled demo database.

*The GIF is built by scripts/make_demo_video.py from real tool outputs on the demo databases (PostGIS and Oracle).*

Türkçe: kullanım kılavuzu aşağıda · Who is it for / step-by-step: Usage

Why another PostGIS / Postgres / Oracle MCP server?

Generic Postgres or Oracle MCP servers are not spatial-aware: the model has to hand-write PostGIS / SDO_* SQL and gets SRIDs, geography casts, units and ST_DWithin / SDO_WITHIN_DISTANCE arguments wrong in subtle ways, then cannot show the result. mapsql-mcp is built around three ideas:

1. Safe by construction. Every query is parsed (PostgreSQL: the real PostgreSQL parser; Oracle: sqlglot in Oracle mode), runs in a READ ONLY transaction with a timeout and a row cap, and secrets never reach the model. Writes are off unless you ask for them (PostGIS only).
2. Spatial tools instead of SQL guessing. within_distance, nearest, buffer, spatial_filter, spatial_join, aggregate, bbox_of ... take care of SRIDs, metric units and indexes - the same 14 tools on both databases. Plain run_sql is still there.
3. Answers are maps. render_map returns a PNG (OpenStreetMap basemap, choropleths, labels) as MCP image content and can also write an interactive Leaflet HTML file.

And the model is told to ask instead of guess: the server instructions, a prompt and the tools themselves refuse to proceed on "pharmacies nearby" (*nearby what?*) or on a place name that matches ten features.

Quickstart

Requires Python 3.10+ and a PostGIS or Oracle Spatial database. Use a read-only database role / user (see SECURITY.md). The backend is chosen from the connection string.

pip install mapsql-mcp            # or: pipx install mapsql-mcp   |   uvx mapsql-mcp

export DATABASE_URL=postgresql://readonly:secret@localhost:5432/gis mapsql-mcp --check # prints PostgreSQL/PostGIS versions and exits

Oracle Spatial instead (python-oracledb thin mode: no Oracle Client install needed) - see "Oracle Spatial" below

pip install "mapsql-mcp[oracle]" export DATABASE_URL="oracle://MAPSQL_RO:secret@dbhost:1521/ORCLPDB1" mapsql-mcp --check

Claude Desktop

Edit claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\):

{

"mcpServers": { "postgis": { "command": "uvx", "args": ["mapsql-mcp"], "env": { "DATABASE_URL": "postgresql://readonly:secret@localhost:5432/gis" } } } }

Claude Code

claude mcp add postgis -e DATABASE_URL=postgresql://readonly:secret@localhost:5432/gis -- uvx mapsql-mcp

Cursor (.cursor/mcp.json) / Windsurf

{

"mcpServers": { "postgis": { "command": "uvx", "args": ["mapsql-mcp", "--schemas", "public,osm"], "env": { "DATABASE_URL": "postgresql://readonly:secret@localhost:5432/gis" } } } }

VS Code (.vscode/mcp.json, Copilot Chat in Agent mode)

VS Code uses a servers key and can prompt for the password instead of storing it in the file:

{

"inputs": [ { "id": "pg-url", "type": "promptString", "description": "PostGIS connection URL", "password": true } ], "servers": { "postgis": { "type": "stdio", "command": "uvx", "args": ["mapsql-mcp", "--schemas", "public,osm"], "env": { "DATABASE_URL": "${input:pg-url}" } } } }

Other MCP clients (ChatGPT-compatible, remote)

Run the streamable-HTTP transport and point the client at http://127.0.0.1:8000/mcp:

mapsql-mcp --transport streamable-http --host 127.0.0.1 --port 8000

There is no authentication on the HTTP transport: keep it on loopback or put it behind your own authenticating reverse proxy / tunnel. If you installed from a clone use "command": "python", "args": ["-m", "mapsql_mcp"].

Usage, step by step

Who it is for. GIS developers, database people, analysts and researchers who already use an AI assistant (Claude Code, Claude Desktop, Cursor, VS Code + Copilot) and have spatial data in PostGIS or Oracle Spatial. It is a building block for an assistant, not an end-user app: there is no web UI of its own, the chat window *is* the UI.

1. Install:

pipx install "mapsql-mcp[oracle]"     # or: pip install "mapsql-mcp[oracle]"

2. Point it at a database with a read-only user and check the connection:

export DATABASE_URL=postgresql://readonly:secret@localhost:5432/gis      # or oracle://USER:PASS@host:1521/service

mapsql-mcp --check

No database at hand? Build the bundled demo (Natural Earth + OpenStreetMap Ankara) in two minutes, see the next section.

3. Register it with your assistant. Put one of the JSON blocks from *Quickstart* into the client's config (.mcp.json for Claude Code, .vscode/mcp.json for VS Code, .cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop). In VS Code click Start above the server entry; in Claude Code run /mcp and check it says *connected*. You should see 14 tools.

4. Ask in plain language. For example:

• *"What layers do you have? Summarise them."*
• *"Which pharmacies are within 500 m of Kızılay (39.9208, 32.8541)? Show them on a map."*
• *"Which neighbourhood has the most cafes? Colour the neighbourhoods by count."*
• *"The 5 hospitals nearest to this point, with distances."*
• *"Find the pharmacies nearby."* - a good assistant asks *nearby what?* instead of guessing.

5. See the map. render_map returns the PNG to the assistant and saves it (and optionally an interactive Leaflet HTML) under ~/mapsql-mcp-output. Some clients (e.g. the Claude Code panel in VS Code) do not show tool images to you; add MAPSQL_OPEN_MAPS=1 (or --open-maps) to the server's env and every map opens in your default viewer.

Good to know. The assistant's provider (Anthropic, OpenAI, ...) receives the rows the tools return, so do not connect databases whose content must not leave your organisation; use --schemas / --layers to expose only what is needed, and keep the database user read-only.

Try it with the demo database (2 minutes)

The demo data is Natural Earth (world countries, provinces, cities, rivers, lakes - public domain) plus an OpenStreetMap extract of central Ankara (POIs, roads, parks, 105 neighbourhoods - ODbL). A pinned snapshot ships in demo/data (2.8 MB), so building it works offline.

docker run -d --name pg -p 55432:5432 -e POSTGRES_PASSWORD=pw postgis/postgis:16-3.4

pip install -e . python demo/build_demo_db.py --database-url postgresql://postgres:pw@localhost:55432/postgres export DATABASE_URL=postgresql://postgres:pw@localhost:55432/postgres

Then ask your assistant, for example:

• *"What layers do you have? Summarise the Ankara data."*
• *"Which neighbourhood has the most pharmacies? Show it as a map."*
• *"Cafes within 300 m of Kızılay (lat 39.9208, lon 32.8541), on a map."*
• *"Find the pharmacies nearby."* → it should ask where.

*Map data © OpenStreetMap contributors (ODbL).* Interactive versions of two of them: docs/images/*.html (open in a browser).

Oracle Spatial

New in v0.2: the same tools, the same safety model and the same maps on Oracle Database with Spatial (19c, 21c, 23ai / 26ai, Autonomous Database, ...), through python-oracledb in *thin* mode (no Oracle Client libraries needed).

*Same question, same answer (20 pharmacies) as on PostGIS - this time from SDO_WITHIN_DISTANCE(... 'distance=500 unit=M') on an Autonomous Database. Map data (c) OpenStreetMap contributors (ODbL).*

Install and connect

pip install "mapsql-mcp[oracle]"        # adds oracledb + sqlglot

All other settings (MAPSQL_SCHEMAS, MAPSQL_LAYERS, MAPSQL_STATEMENT_TIMEOUT_MS, MAPSQL_MAX_ROWS, ...) work unchanged; the timeout is applied as the connection call_timeout, schemas are Oracle *owners*.

Autonomous Database (TLS, no wallet). In the console open *Database connection*, choose *TLS authentication: TLS* (instead of mTLS; requires an access control list / allowed IPs for your address) and copy the Low/Medium connection string. The descriptor looks like (description=(address=(protocol=tcps)(port=1522)(host=...))(connect_data=(service_name=...))(security=(ssl_server_dn_match=yes))); put it in MAPSQL_ORACLE_DSN (it is long and contains parentheses, so it does not fit well in a URL). The server certificate is verified against the operating system's trust store. Use a dedicated read-only user, never ADMIN.

export MAPSQL_ORACLE_DSN='(description=(retry_count=3)(address=(protocol=tcps)(port=1522)(host=adb.<region>.oraclecloud.com))(connect_data=(service_name=xxxx_my