3dcitydb-mcp-server 0.1.1

MCP server for natural-language querying of 3DCityDB v5 semantic city models

3DCityDB MCP Server

A Model Context Protocol (MCP) server that gives AI assistants (Claude Code, Claude Desktop, and any MCP-compatible client) direct, intelligent access to 3DCityDB v5 semantic city models.

It dynamically resolves object classes, properties, codelists, and generic attributes from the database so the AI can answer spatial questions, write and execute SQL queries, and reason about CityGML data — without any manual prompt engineering.

Features

• Dynamic schema resolution — walks the CityGML class hierarchy to discover available object classes and their properties
• Property filtering — only includes properties that actually exist in the database (CityGML schema → 3DCityDB instance → populated attributes)
• Codelist resolution — fetches code meanings only for codes present in the DB
• Generic attribute enrichment — automatic categorical detection for generic attributes
• Read-only query execution — run_query enforces SELECT-only; writes are blocked
• Prompt assembly — assemble_prompt orchestrates all tools into a complete system prompt in one call

Prerequisites

• Python 3.10+
• A running 3DCityDB v5 PostgreSQL instance with PostGIS

Installation

pip install 3dcitydb-mcp-server

Or, to install from source for development:

git clone https://github.com/tum-gis/3dcitydb-mcp-server.git
cd 3dcitydb-mcp-server/mcp-server
pip install -e .

Configuration

Copy the example environment file and edit it:

# Linux / macOS
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Then fill in your 3DCityDB connection details:

# --- 3DCityDB PostgreSQL connection ---
CITYDB_HOST=localhost
CITYDB_PORT=5432
CITYDB_NAME=citydb
CITYDB_USER=postgres
CITYDB_PASSWORD=your_password_here
CITYDB_SCHEMA=citydb

# --- Query behaviour (optional) ---
CATEGORICAL_THRESHOLD=20
SAMPLE_VALUES_COUNT=5

The server loads .env automatically by searching upward from the working directory, so no extra setup is needed.

Running

1. Verify your installation

3dcitydb-doctor

Checks Python version, all required packages, database connectivity, PostGIS/SFCGAL extensions, and 3DCityDB v5 schema. Exits 0 if all critical checks pass.

2. Connect to Claude Code (recommended)

From your project directory (where your .env lives):

claude mcp add 3dcitydb -- 3dcitydb-mcp

Then start a session:

claude

The MCP server starts automatically. Use /mcp inside the session to confirm it is connected.

3. Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "3dcitydb": {
      "command": "3dcitydb-mcp",
      "cwd": "/path/to/your/project"
    }
  }
}

4. SSE transport (remote / production)

3dcitydb-mcp-sse --host 0.0.0.0 --port 8080

Clients connect via: http://your-server:8080/sse
Health check: http://your-server:8080/health

5. Docker

docker build -t 3dcitydb-mcp .
docker run -p 8080:8080 --env-file .env 3dcitydb-mcp

Available MCP Tools

Static (cached per session)

Tool	Description
get_database_schema	3DCityDB v5 table structures and foreign key relationships
get_query_guidelines	SQL best practices and optimization tips for 3DCityDB

Dynamic (called at session start)

Tool	Description
scan_objectclasses	Discover available object classes with full hierarchy
resolve_properties(objectclass_id)	Resolve properties with codelists for a given class
get_generic_attributes	Generic attributes with categorical detection
get_db_context_snapshot	SRS, bounding box, feature counts, statistics
get_lod_config	Available Levels of Detail in the database
get_examples(objectclass_ids)	SQL examples filtered to existing object classes

Runtime (per query)

Tool	Description
run_query(sql)	Execute read-only SQL (SELECT/WITH only) against 3DCityDB
get_session_context	Session management
update_module_selection	Narrow scope to specific object classes
get_history	Conversation history for a session
submit_feedback	Log query feedback

Assembly

Tool	Description
assemble_prompt	Orchestrates all tools into a complete system prompt

Architecture

  Claude Code / Claude Desktop / any MCP client
                      |
               MCP Protocol (stdio / SSE)
                      |
       +--------------+--------------+
       |   3DCityDB MCP Server       |
       |   assemble_prompt()         |
       |   scan_objectclasses()      |
       |   run_query()               |
       +--------------+--------------+
                      |
                 3DCityDB v5
               (PostgreSQL + PostGIS)

License

The 3DCityDB MCP server is distributed under the Apache License 2.0. See LICENCE for more information.