Skip to main content
Glama
cityjson-mcp

cityjson-mcp

by Yarroudh

CityJSON MCP

CityJSON MCP provides a web chat application and an MCP server for CityJSON files. It supports inspection, queries, validation, transformations, export, CityGML conversion, and cjdb/PostGIS operations.

The Docker image includes:

  • cjio for CityJSON transformations and export.

  • cjval for syntax, schema, and structural validation.

  • val3dity for 3D geometry validation.

  • citygml-tools for CityGML and CityJSON conversion.

  • cjdb for PostgreSQL/PostGIS import and export.


Demo

The following video is a demo of Datum, the chat application in this repository. It shows importing a CityJSON file, inspecting it, creating a subset, and downloading the derived dataset.

Datum demo


Related MCP server: Battenmark

Quick start: Datum chat application

Datum is the official AI client provided with CityJSON MCP toolbox. It accepts CityJSON attachments in the browser, and lets a configured LLM model call the CityJSON tools to process datasets and answer user questions.

For a complete visual tour of the interface and its behavior, see the Datum guide.

For every supported setup path and environment option, see Installation and configuration.

Requirements

  • Docker Desktop or Docker Engine with Docker Compose.

  • Node.js 20 or newer.

  • An API key for a cloud model that supports tool calls, or a local Ollama model.

Datum supports local Ollama models. However, for optimal performance and reliability, we recommend using a cloud model. Local models may encounter memory constraints, particularly with larger workloads, and have not yet been extensively tested.

1. Install the JavaScript dependencies

npm install

2. Create .env

Copy the example file:

cp .env.example .env

Set these values before starting Datum:

MODEL_PROVIDER=openrouter
MODEL_NAME=openrouter/free
MODEL_API_KEY=replace-with-your-openrouter-api-key
MODEL_BASE_URL=https://openrouter.ai/api/v1
MODEL_TEMPERATURE=0.1

The model settings mean:

Variable

Required

Description

MODEL_PROVIDER

yes

Model service: ollama, openrouter, openai, or anthropic. Ollama, OpenRouter, and services compatible with OpenAI use the OpenAI Chat Completions format internally.

MODEL_NAME

yes

Exact model identifier sent to the provider, for example openrouter/free. The model must support tool calls.

MODEL_API_KEY

except Ollama

API credential issued by the model provider. Local Ollama needs no key. Do not commit .env.

MODEL_BASE_URL

yes

Base URL for the provider API.

MODEL_TEMPERATURE

no

Sampling temperature. Datum defaults to 0.1.

OLLAMA_CONTEXT_LENGTH

no

Ollama context window in tokens. Defaults to 16384; larger values use more RAM or VRAM.

The .env model is the default model in Datum. Users can add other models from the model menu in the UI. Models added through the interface remain in server memory for up to eight hours. Their API keys are not returned to the browser or passed to MCP tools.

Cloud model providers

Datum supports OpenRouter, APIs compatible with OpenAI, and Anthropic as cloud providers. Credentials stay in the running application and are not passed to MCP tools. Datum checks whether each model can call a tool before accepting it because catalog metadata alone does not guarantee reliable agent behavior.

Create an OpenRouter API key, choose OpenRouter (cloud catalog) in Datum, and paste the key. Select Free Models Router at the top of the refreshed catalog. It uses the stable openrouter/free ID and automatically selects an available free model compatible with requested features such as tool calling.

To make it the default:

MODEL_PROVIDER=openrouter
MODEL_NAME=openrouter/free
MODEL_API_KEY=paste-your-openrouter-key-here
MODEL_BASE_URL=https://openrouter.ai/api/v1
MODEL_TEMPERATURE=0.1

This is Datum's recommended configuration for a free cloud model. It avoids depending on one provider's free capacity, but the selected model can vary between calls. Free usage is intended for experimentation and small workloads, has rate limits, and may be less predictable than paid inference. You can still select a specific :free model when model consistency matters more than automatic availability.

OpenAI GPT Nano

Use the OpenAI choice with an API key:

MODEL_PROVIDER=openai
MODEL_NAME=gpt-5-nano
MODEL_API_KEY=paste-your-openai-api-key-here
MODEL_BASE_URL=https://api.openai.com/v1

GPT-5 Nano supports function calling but the OpenAI API does not provide it on the free usage tier. It is inexpensive and useful for testing, although a stronger coding model may be more reliable for long CityJSON tool workflows.

Other providers compatible with OpenAI

For any service with an API compatible with OpenAI Chat Completions, choose the OpenAI API option in Datum, then enter the provider's exact model ID, API key, and base URL. This covers services such as Gemini and DeepSeek without maintaining a provider directory in the code. Services requiring a different protocol, OAuth flow, or custom request headers are not automatically compatible.

MODEL_API_KEY takes precedence for the default model. Datum also recognizes OPENROUTER_API_KEY, OPENAI_API_KEY, and ANTHROPIC_API_KEY for their matching MODEL_PROVIDER. All of these model credentials are removed from the environment passed to the MCP subprocess.

For free experimentation, use openrouter/free as shown above. OpenRouter chooses a currently available free model and filters for capabilities required by the request. Its free tier has limited request quotas, and capacity can fluctuate between providers.

For the best reliability and more demanding CityJSON tool workflows, use a paid Gemini or DeepSeek model through its API that is compatible with OpenAI. Choose the OpenAI API option in Datum and enter the provider's model ID, API key, and base URL. Paid models avoid the tight capacity limits of free endpoints and keep the model stable throughout a conversation.

Google API keys are managed in Google AI Studio; see Google's OpenAI compatibility guide and pricing. For DeepSeek, use its API documentation and pricing. Review each provider's data policy before sending confidential CityJSON datasets.

Local models with Ollama

Ollama is an optional companion service. A normal npm run chat enables it automatically only when .env has MODEL_PROVIDER=ollama. Configurations with a cloud model start Datum without inspecting, pulling, or starting the Ollama image. The launcher prints the selected mode before it checks Docker images.

Override the automatic choice when needed:

# Keep Ollama available alongside a cloud default
npm run chat -- --with-ollama

# Start only Datum, even if .env currently selects Ollama
npm run chat -- --without-ollama

For a persistent setting, use CHAT_ENABLE_OLLAMA=true or CHAT_ENABLE_OLLAMA=false in .env. Command line flags take precedence. If Ollama is enabled, no separate installation is required: the launcher first looks for native Ollama on macOS and otherwise pulls the official image when missing. Docker model downloads remain in the ollama-models volume.

To make an Ollama model the default, configure .env:

MODEL_PROVIDER=ollama
MODEL_NAME=qwen3:8b
MODEL_API_KEY=
MODEL_BASE_URL=http://ollama:11434/v1
MODEL_TEMPERATURE=0.1
OLLAMA_CONTEXT_LENGTH=16384

❗ Important: Always make sure to use a model that supports tool calls. For more information, please refer to: https://ollama.com/search?c=tools

When Ollama is enabled, you can select it in Datum and pull a model with the add button. npm run chat:stop stops the active containers without deleting downloaded models. Deleting a model from Datum removes only its saved configuration; it does not remove the downloaded model from Ollama. If you want the downloaded model deleted, please use the following command:

ollama rm <model-name>

Local model quality and memory requirements vary. Datum evaluates a model's metadata and actual call output, then marks it Recommended or Limited in the model menu. Limited models remain usable, but may be less reliable for CityJSON workflows.

The default 16384 tokens context is a practical balance. Use 8192 if you have memory constraints or 32768 for longer conversations when sufficient memory is available. For bundled Docker Ollama, change OLLAMA_CONTEXT_LENGTH in .env and restart Datum. For native Ollama, set the same variable when launching Ollama and restart that service. Ollama applies this globally because its API endpoint does not accept the context size per request.

Other model services

Datum can use any model that supports tool calls through one of its two API formats. Examples:

Service

MODEL_PROVIDER

Example model

MODEL_BASE_URL

Ollama

ollama

qwen3:8b

http://ollama:11434/v1

OpenRouter

openrouter

select a model that supports tools from the live catalog

https://openrouter.ai/api/v1

Google Gemini

openai

gemini-3.7-flash

https://generativelanguage.googleapis.com/v1beta/openai

DeepSeek

openai

deepseek-v4-pro

https://api.deepseek.com

OpenAI GPT

openai

a current GPT model with Chat Completions tool calling

https://api.openai.com/v1

Anthropic Claude

anthropic

a current Claude model with tool use

https://api.anthropic.com

Model names and availability change. Confirm the exact model identifier in the provider documentation:

3. Start Datum

npm run chat

Open http://127.0.0.1:3000, or the port set by CHAT_PORT in .env.

The command starts the container in detached mode and returns to the terminal. Use these commands to view logs or stop the application:

npm run chat:logs
npm run chat:stop

npm run chat uses this sequence to select images:

  1. Read .env and resolve Ollama mode from --with-ollama, --without-ollama, CHAT_ENABLE_OLLAMA, or MODEL_PROVIDER, in that order.

  2. Print whether startup uses a cloud model, native Ollama, or bundled Ollama.

  3. If Ollama is enabled on macOS, use a running native service when detected; otherwise pull the official Ollama image only when it is missing.

  4. Check whether the CityJSON MCP image exists and pull it when missing.

  5. Start Datum and, when selected, its Ollama companion in detached mode without building an image.

The application binds to 127.0.0.1:${CHAT_PORT:-3000}. Set CHAT_PORT in .env before starting Datum to change both the published Docker port and the application port. Docker volumes store imported files, derived datasets, and downloaded Ollama models. Ollama is available only to the internal Compose network and is not published on a host port.

Optional: build the image locally

Build the image before npm run chat when you want to run local source changes:

npm run docker:cache:val3dity
npm run docker:cache:cjval
npm run docker:build
npm run docker:doctor
npm run chat

The val3dity and cjval build stages take the most time. They can be cached separately.

Set CITYJSON_MCP_IMAGE to use your created Docker image.


Use the MCP server without Datum

The MCP server can run separately in Claude Desktop, Claude Code, Cursor, VS Code, or another client that supports local stdio MCP servers. A separate model API key is not required by the MCP server because the client supplies the model.

Pull and verify the image

docker pull yarroudh/cityjson-mcp:latest
docker run --rm --entrypoint node yarroudh/cityjson-mcp:latest /app/scripts/doctor.mjs

The doctor command should report OK for cjio, cjval, val3dity, citygml-tools, and cjdb.

Upload a file from Claude Desktop or another MCP client

The default setup needs no project folder. Add this server configuration:

{
  "mcpServers": {
    "cityjson": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--mount",
        "type=volume,source=cityjson-mcp-data,target=/data",
        "yarroudh/cityjson-mcp:latest"
      ]
    }
  }
}

Then ask the client:

Upload my CityJSON file and summarize its buildings.

The cityjson_upload tool opens a file picker in MCP Apps compatible clients, including Claude Desktop. Choose or drop the file there. The app transfers the file in chunks directly to the MCP server, then continues the question using the file's name. The model does not receive the full CityJSON text. Docker creates the storage volume automatically.

Attaching a file to the chat composer is a separate client feature. If the client gives the model the complete text of a small JSON attachment, cityjson_import_text can use it immediately with its original filename; you do not need to select it again. For larger files, choose the file in the CityJSON upload panel: chat attachments are not automatically passed to an MCP server. MCP Apps provides this panel inside the chat, while general file transfer is still being developed as an MCP extension. Clients without MCP Apps support can configure a shared folder for larger files. Datum's browser upload works directly without this panel.

To let the server open files already present in a project folder, add an optional bind mount with read only access, such as --mount type=bind,source=/absolute/path/to/project,target=/project,readonly, and set CITYJSON_MCP_ALLOWED_ROOTS=/project. Then ask about the file by name; cityjson_open finds and snapshots it. Files in subfolders can also be found by name, and duplicate names can be disambiguated with a relative path.

Claude Desktop

The template needs no folder configuration: config/claude-desktop.json.

Claude Desktop configuration locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge the mcpServers.cityjson entry into the existing file. Fully quit and reopen Claude Desktop. In a chat, enable the cityjson connector and allow its tools.

Claude Code

Copy the template into the project where Claude Code runs:

cp config/claude-code.json .mcp.json

Restart or reconnect the MCP server after adding .mcp.json.

Cursor

The template is config/cursor-mcp.json.

Use one of these locations:

  • Project: .cursor/mcp.json

  • Global: ~/.cursor/mcp.json

Restart the MCP server after changing the file.

VS Code

The template is config/vscode-mcp.json. Copy its servers.cityjson entry into .vscode/mcp.json, then start or restart the server from the MCP server management commands in VS Code.

Other MCP clients

Use this command for any client that supports a local stdio MCP server:

docker run --rm -i yarroudh/cityjson-mcp:latest

Add the optional /project mount shown above when the server must read existing local files directly.


Architecture

flowchart LR
  CLIENT["Clients"]
  BROWSER["Interface"]
  CHAT["Host<br/>model control<br/>tool client"]
  MODEL["Model"]
  INPUT["Input<br/>streamed city data"]

  SERVER["Server"]
  CORE["Data manager<br/>handles<br/>access rules"]

  NATIVE["Query<br/>metadata<br/>objects<br/>bounds"]
  CJIO["cjio<br/>transform<br/>subset<br/>export"]
  CJVAL["cjval<br/>schema<br/>structure"]
  VAL3["val3dity<br/>geometry validation"]
  CGML["citygml-tools<br/>format conversion"]
  CJDB["cjdb<br/>storage"]
  KNOW["CityJSON references<br/>specification<br/>schemas<br/>extensions"]

  CLIENT -->|protocol| SERVER

  BROWSER --> CHAT
  BROWSER -->|file stream| INPUT

  CHAT --> MODEL
  CHAT -->|protocol| SERVER

  INPUT --> CORE
  SERVER --> CORE

  CORE --> NATIVE
  CORE --> CJIO
  CORE --> CJVAL
  CORE --> VAL3
  CORE --> CGML
  CORE --> CJDB

  SERVER --> KNOW

Tool catalog

The standalone server exposes 38 tools to users. Datum uses its 37 tools and its own browser upload.

For complete parameter schemas, backend behavior, return values, and example workflows, see the CityJSON MCP tools reference.

Dataset management and inspection

Tool

Backend

Purpose

cityjson_backend_status

native

Report backend availability and path settings.

cityjson_list_imports

native

List JSON files in the input directory.

cityjson_import

native

Register a file delivered to Datum's input inbox.

cityjson_upload

native

Show a file picker in the chat and upload directly to the MCP server.

cityjson_import_text

native

Import a small CityJSON document supplied as text.

cityjson_open

native

Open a project file by name or path and snapshot it.

cityjson_download

native

Return a source or derived CityJSON file.

cityjson_save

native

Copy a dataset to an authorized destination.

cityjson_info

native

Return version, counts, LoDs, attributes, metadata, transform, and extensions.

cityjson_list_objects

native

List CityObjects with pagination and type filters.

cityjson_get_object

native

Return one CityObject and its computed bounding box.

cityjson_query

native

Query by IDs, types, bounding box, and attribute predicates.

Validation

Tool

Backend

Purpose

cityjson_validate_schema

cjval

Validate JSON syntax, schemas, extensions, and structural consistency.

cityjson_validate_geometry

val3dity

Validate supported 3D geometry primitives.

cityjson_validate

cjval + val3dity

Run both validators and return one result.

Transformations

Each tool in this table returns a new filename for the derived CityJSON file.

Tool

Backend

Purpose

cityjson_subset

cjio

Select or exclude objects by IDs, type, bounding box, radius, or random count.

cityjson_filter_lod

cjio

Keep one level of detail.

cityjson_reproject

cjio

Transform coordinates to a target EPSG CRS.

cityjson_assign_crs

cjio

Assign an EPSG CRS without changing coordinates.

cityjson_translate

cjio

Translate coordinates.

cityjson_clean_vertices

cjio

Remove duplicate and unused vertices.

cityjson_triangulate

cjio

Triangulate surfaces.

cityjson_merge

cjio

Merge two or more datasets.

cityjson_attribute_rename

cjio

Rename an attribute.

cityjson_attribute_remove

cjio

Remove an attribute.

cityjson_remove_textures

cjio

Remove textures.

cityjson_remove_materials

cjio

Remove materials.

cityjson_upgrade

cjio

Upgrade an older supported CityJSON version.

Export, conversion, and database

Tool

Backend

Purpose

cityjson_export

cjio

Export to JSONL, OBJ, STL, GLB, or B3DM.

citygml_to_cityjson

citygml-tools

Convert CityGML to CityJSON or CityJSONSeq.

cityjson_to_citygml

citygml-tools

Convert CityJSON to CityGML.

cityjson_db_import

cjio + cjdb

Import a dataset into PostgreSQL/PostGIS.

cityjson_db_export

cjdb + cjio

Export all or selected objects from cjdb.

Specification and schemas

Tool

Source

Purpose

cityjson_spec_outline

bundled index

Return the CityJSON specification outline and schema names.

cityjson_spec_read

cityjson.org

Read part of the CityJSON specification.

cityjson_schema_read

cityjson.org

Read a CityJSON JSON Schema.

cityjson_extensions_registry

CityJSON registry

List or search registered extensions.

cityjson_extension_schema

CityJSON registry

Read a registered extension schema.


Example prompts

Inspect a file

Report the version, CRS, object counts by type, LoDs, attributes, and extensions in model.city.json. Do not modify the file.

Expected tools: cityjson_open, cityjson_info.

Validate a file

Run structural and geometric validation on model.city.json. Separate cjval findings from val3dity findings and list affected object IDs.

Expected tools: cityjson_open, cityjson_validate.

Create a subset

In model.city.json, keep Building and BuildingPart objects inside bbox [85000, 446000, 86000, 447000], keep LoD 2.2, reproject to EPSG:28992, validate the result, and give me the resulting file.

Expected tools: cityjson_open, cityjson_subset, cityjson_filter_lod, cityjson_reproject, cityjson_validate, cityjson_download.

Clean and download

Remove duplicate and unused vertices from model.city.json, validate the result, and return it as tile-clean.city.json. Do not overwrite the source.

Expected tools: cityjson_open, cityjson_clean_vertices, cityjson_validate, cityjson_download.

In Datum, attach a CityJSON file directly using the Import CityJSON button or drag and drop. Datum registers it automatically.


Configuration reference

Variable

Default

Purpose

MODEL_PROVIDER

anthropic

Model service: ollama, openrouter, openai, or anthropic.

MODEL_NAME

none

Default Datum model identifier.

MODEL_API_KEY

none

Default Datum model API key.

MODEL_BASE_URL

provider default

Model API base URL.

MODEL_MAX_OUTPUT_TOKENS

4096

Maximum output tokens per model call.

MODEL_TEMPERATURE

0.1

Model sampling temperature.

CHAT_ENABLE_OLLAMA

automatic

Start bundled/native Ollama with Datum. When unset, enabled only for MODEL_PROVIDER=ollama; CLI flags override it.

CHAT_HOST

127.0.0.1

Datum bind address outside Docker.

CHAT_PORT

3000

Datum port.

CHAT_MAX_UPLOAD_BYTES

1073741824

Maximum upload size.

CHAT_MAX_UPLOAD_FILES

5

Maximum files per upload.

CHAT_MAX_TOOL_ROUNDS

12

Maximum rounds of tool calls per response.

CITYJSON_MCP_ALLOWED_ROOTS

current directory

Authorized filesystem roots. Use : on macOS/Linux and ; on Windows.

CITYJSON_MCP_INPUT

./input

Input directory used by cityjson_import.

CITYJSON_MCP_WORKSPACE

./.cityjson-mcp-workspace

Managed source and derived datasets.

CITYJSON_MCP_COMMAND_TIMEOUT_MS

120000

External command timeout.

CITYJSON_MCP_MAX_DIRECT_UPLOAD_BYTES

104857600

Maximum file size for the CityJSON picker in the chat.

CITYJSON_MCP_MAX_DOWNLOAD_BYTES

26214400

Maximum inline MCP download size. Datum streams downloads directly.

CJIO_BIN

cjio

Optional cjio executable override.

CJVAL_BIN

cjval

Optional cjval executable override.

VAL3DITY_BIN

val3dity

Optional val3dity executable override.

CITYGML_TOOLS_BIN

citygml-tools

Optional citygml-tools executable override.

CJDB_BIN

cjdb

Optional cjdb executable override.

Set PGPASSWORD in the process environment for cjdb. Database tool arguments do not accept a password.


Running without Docker requires Node.js and the backend executables used by the requested tools.

npm install
npm run doctor
npm test
npm run check
npm start

Install Ollama manually

Manual Ollama installation is needed only when running Datum directly with npm run chat:host or when using Ollama outside this project's Docker stack.

  • macOS: download the .dmg from the official Ollama download page, move Ollama to Applications, and launch it. macOS 14 or newer is required.

  • Windows: download and run OllamaSetup.exe from the official Ollama download page. Ollama starts in the background and exposes its API on port 11434.

  • Linux: install and start Ollama with:

    curl -fsSL https://ollama.com/install.sh | sh
    ollama serve

In another terminal, pull a model that supports tool calls and verify the installation:

ollama pull qwen3:8b
curl http://127.0.0.1:11434/api/tags

For host mode, use this model configuration:

MODEL_PROVIDER=ollama
MODEL_NAME=qwen3:8b
MODEL_API_KEY=
MODEL_BASE_URL=http://127.0.0.1:11434/v1
OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
OLLAMA_CONTEXT_LENGTH=16384

Then start Datum with npm run chat:host. Native Ollama is recommended on macOS when model performance matters because it can use Apple Metal acceleration; the Docker Desktop container cannot use the Mac GPU.

Backend installation sources:

Use npm run chat:host only when all required backends are installed locally. Datum checks backend availability during startup. CHAT_ALLOW_PARTIAL_BACKENDS=true allows startup with missing backends for development tests.


Security

  • File operations are limited to CITYJSON_MCP_ALLOWED_ROOTS, the input directory, and the managed workspace.

  • Browser uploads receive generated storage names.

  • MCP tools do not expose arbitrary shell commands.

  • External commands use argument arrays with shell: false.

  • Tool inputs are validated with Zod schemas.

  • Database passwords remain in the process environment.

  • cjdb export accepts only a single SELECT statement, but this check is not a database security boundary. Use a database role with limited permissions.

  • Commands have time and output limits.

  • Treat installation of any local MCP server as installation of local code.


Contributing

  1. Fork the repository and create a branch for one change.

  2. Install dependencies with npm install.

  3. Make the change. Keep MCP tool inputs typed and do not run shell commands from strings.

  4. Add or update tests for changed behavior.

  5. Run:

    npm test
    npm run check
  6. If the change affects a Docker backend, build the image and run npm run docker:doctor.

  7. Update the README and .env.example when configuration or behavior visible to users changes.

  8. Open a pull request that states what changed, why it changed, and how it was tested.

Do not include API keys, database passwords, private CityJSON datasets, generated workspaces, or .env files in a contribution.


Next

  • Add explicit Ollama setup and model presets for local models.

  • Stream model responses and tool progress to the browser.

  • Add cancellation and progress reporting for long validation and conversion jobs.

  • Add an optional 3D preview for imported and derived datasets.


Tests

Run the test suite:

npm test

Run syntax checks for project .mjs files:

npm run check

Verify every executable in the Docker image:

npm run docker:doctor

Known limitations

  • Dataset handles are restored after a restart when the managed workspace is persisted. Without a persistent workspace, opened and derived files from the old container are unavailable.

  • Native inspection loads regular CityJSON files into memory.

  • cityjson_query computes bounding boxes from geometry stored directly on each object. It does not combine all child geometry into a parent bounding box.

  • Specification, schema, and extension lookup tools require network access, except for cityjson_spec_outline.

  • Derived workspace files are not deleted automatically.

  • Exact export and conversion behavior depends on the installed backend versions.

  • val3dity is GPL-3.0 software and runs as a separate executable. Review upstream licenses before redistributing a modified image.


Issues and Feedback

If you encounter a bug, unexpected behavior, or have a suggestion for improvement, please open an issue in the repository.

When reporting an issue, include as much relevant information as possible, such as:

  • A clear description of the problem

  • Steps to reproduce the issue

  • Expected and actual behavior

  • Relevant logs or error messages

  • Your environment and configuration, when applicable

Feature requests and other constructive feedback are also welcome. Before opening a new issue, please check the existing issues to avoid duplicates.


Upstream Projects

This project builds on and integrates with several projects and specifications from the CityJSON, 3D city modelling, and Model Context Protocol ecosystems.

CityJSON

CityJSON Tools

  • cjio: Command line tools and Python utilities for working with CityJSON.

  • cjval: Validation tools for CityJSON datasets.

  • cjdb: Database tools for storing and querying CityJSON data.

  • val3dity: Validation of 3D geometries and 3D city models.

  • citygml-tools: Command line tools for processing and converting CityGML datasets.

Model Context Protocol

These projects are developed and maintained independently by their respective authors and communities. Please refer to their repositories for documentation, licensing, and support.


Citation

We are committed to supporting open and reproducible research and welcome the use of this project in academic and scientific work. If you use this project in your research, please cite it as follows:

APA

Yarroudh. (2026). Yarroudh/cityjson-mcp: CityJSON MCP & Datum Chat Application (Version 0.2.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.22151334

IEEE

[1] Yarroudh, Yarroudh/cityjson-mcp: CityJSON MCP & Datum Chat Application (Version 0.2.0). (Aug. 28, 2026). Zenodo. doi: 10.5281/zenodo.22151334.

BibTeX

@software{yarroudh2026cityjsonmcp,
  author    = {Yarroudh},
  title     = {Yarroudh/cityjson-mcp: CityJSON MCP \& Datum Chat Application},
  year      = {2026},
  version   = {0.2.0},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22151334},
  url       = {https://doi.org/10.5281/zenodo.22151334}
}

License

This repository uses the MIT License. See LICENSE.

The bundled image invokes external programs under their own licenses. This repository does not relicense those programs.


About Developer

This project is developed and maintained by Anass Yarroudh, a Data Scientist and Machine Learning Engineer at GIM, and a Research Associate at the University of Liège.

This repository is a personal side project developed independently and is not affiliated with, endorsed by, or maintained on behalf of any of my professional or academic affiliations.

For professional inquiries or to connect, feel free to reach out on LinkedIn.

Available Tools

42 tools
citygml_to_cityjsonConvert CityGML to CityJSONB

Convert a CityGML 1.0/2.0/3.0 GML/XML file to CityJSON using citygml-tools. A regular CityJSON output is automatically registered and returned by filename.

Inputs: source (required), json_lines.

cityjson_assign_crsAssign CityJSON CRSA

Assign/update the EPSG reference without changing coordinate values using cjio. Returns a new filename.

Inputs: epsg (required), dataset_id (required).

cityjson_attribute_removeRemove CityJSON attributeC

Remove an attribute across CityObjects with cjio.

Inputs: name (required), dataset_id (required).

cityjson_attribute_renameRename CityJSON attributeC

Rename an attribute across CityObjects with cjio.

Inputs: new_name (required), old_name (required), dataset_id (required).

cityjson_backend_statusCityJSON backend statusA

Check which external CityJSON/CityGML engines are installed and callable. Run this first when a backend-dependent operation fails.

Inputs: no named parameters.

cityjson_clean_verticesClean CityJSON verticesB

Remove duplicate and orphan vertices with cjio vertices_clean. Returns a new filename.

Inputs: dataset_id (required).

cityjson_db_exportExport CityJSON from cjdbA

Export all objects or a read-only SELECT-defined subset from cjdb to CityJSONSeq and optionally collect it into a named CityJSON file.

Inputs: connection (required), query, collect.

cityjson_db_importImport CityJSON into cjdbB

Convert the dataset to CityJSONSeq with cjio and import it into PostgreSQL/PostGIS using cjdb. PostgreSQL password should be supplied through PGPASSWORD, not tool arguments.

Inputs: connection (required), dataset_id (required), attribute_indexes, partial_attribute_indexes.

cityjson_downloadDownload CityJSON contentA

Prepare an opened or transformed dataset for download. The web host streams the managed file directly; standalone MCP clients receive an embedded application/json resource within the configured inline-size limit.

Inputs: dataset_id (required), filename.

cityjson_exportExport CityJSONC

Export an opened CityJSON dataset with cjio to jsonl, obj, stl, glb or b3dm.

Inputs: format (required), dataset_id (required), destination (required), sloppy.

cityjson_extension_schemaRead a CityJSON Extension schemaB

Fetch a registered CityJSON Extension schema from the canonical cityjson.github.io registry URL.

Inputs: name (required), version (required).

cityjson_extensions_registryBrowse CityJSON Extensions registryC

Fetch the official CityJSON Extensions registry and optionally return context around a search term.

Inputs: query, max_chars.

cityjson_filter_lodFilter CityJSON LoDC

Keep only one level of detail using cjio lod_filter. Returns a new filename.

Inputs: lod (required), dataset_id (required).

cityjson_get_objectGet CityObjectB

Return one complete CityObject and a computed real-world bounding box derived from referenced vertices.

Inputs: object_id (required), dataset_id (required).

cityjson_importImport CityJSON from the input inboxA

Register a CityJSON file already placed in the configured input inbox and return its filename. This is for clients with an upload bridge, such as Datum. If filename is omitted, the inbox must contain exactly one JSON file.

Inputs: filename, display_filename.

cityjson_import_textImport a small CityJSON text documentA

Import a small complete CityJSON document already available as text, including a small chat attachment exposed to the model by the client. Preserve the original filename. For missing, incomplete, or large attachments, use cityjson_upload.

Inputs: content (required), filename.

cityjson_infoInspect CityJSONB

Return metadata, object counts, types, LoDs, attribute names, transform and extensions for an opened dataset.

Inputs: dataset_id (required).

cityjson_list_importsList CityJSON input filesA

List JSON files in the configured input inbox. Use this when the user did not name an attached/imported file or when cityjson_import reports multiple candidates. Returns filenames only; never ask the user for an absolute path.

Inputs: no named parameters.

cityjson_list_objectsList CityObjectsB

List CityObjects with IDs, types, selected attributes and LoDs. Supports filtering by CityObject type and pagination.

Inputs: dataset_id (required), limit, types, offset.

cityjson_mergeMerge CityJSON datasetsB

Merge two or more opened CityJSON files with cjio. Returns a new filename.

Inputs: dataset_ids (required).

cityjson_openOpen a CityJSON fileA

Open a CityJSON file from an optional configured project or data folder by filename, relative path, or full server-visible path. The server snapshots the file and returns its filename for later tools.

Inputs: source (required).

cityjson_queryQuery CityObjectsC

Query CityObjects natively by IDs, types, 2D bbox and attribute predicates. Attribute predicates support eq, neq, gt, gte, lt, lte, contains and in.

Inputs: dataset_id (required), ids, bbox, limit, +3 more.

cityjson_remove_materialsRemove CityJSON materialsB

Remove all materials with cjio. Returns a new filename.

Inputs: dataset_id (required).

cityjson_remove_texturesRemove CityJSON texturesB

Remove all textures with cjio. Returns a new filename.

Inputs: dataset_id (required).

cityjson_reprojectReproject CityJSONA

Reproject coordinates to a target EPSG CRS with cjio. The source file must already define a CRS. Returns a new filename.

Inputs: epsg (required), dataset_id (required), digit.

cityjson_saveSave CityJSONC

Copy an opened/derived CityJSON dataset to an explicit destination path.

Inputs: dataset_id (required), destination (required), overwrite.

cityjson_schema_readRead CityJSON JSON SchemaA

Fetch one canonical CityJSON 2.0.2 JSON Schema by name.

Inputs: name.

cityjson_spec_outlineCityJSON specification outlineA

Return the bundled outline and canonical URLs for the current CityJSON specification and schemas.

Inputs: no named parameters.

cityjson_spec_readRead CityJSON specificationA

Fetch the canonical CityJSON 2.0.2 living specification and return either the beginning or a context window around a search query.

Inputs: query, max_chars.

cityjson_subsetCreate CityJSON subsetB

Create a derived CityJSON subset with cjio using IDs, bbox, radius, random count or CityObject types. Returns a new filename.

Inputs: dataset_id (required), ids, bbox, types, +3 more.

cityjson_to_citygmlConvert CityJSON to CityGMLB

Convert an opened CityJSON dataset to CityGML using citygml-tools. The installed citygml-tools version controls the default target encoding.

Inputs: dataset_id (required), crs_name, output_directory.

cityjson_translateTranslate CityJSON coordinatesB

Translate CityJSON coordinates with cjio. With minxyz, coordinates are shifted relative to the supplied minimum; without it cjio uses the model minimum.

Inputs: dataset_id (required), minxyz.

cityjson_triangulateTriangulate CityJSONB

Triangulate surfaces with cjio. Use sloppy=true only when the robust triangulator fails.

Inputs: dataset_id (required), sloppy.

cityjson_upgradeUpgrade CityJSONB

Upgrade an older supported CityJSON file to the version supported by the installed cjio.

Inputs: dataset_id (required).

cityjson_uploadUpload a CityJSON fileA

Open an in-chat file picker to upload a CityJSON file directly. Use this when the user attached or wants to choose a file that is not visible to the MCP server. The file is transferred outside the model context; no project folder or workspace setup is needed. Pass the user’s question so the app can continue after upload.

Inputs: question.

cityjson_upload_cancelCancel CityJSON uploadC

Discard an unfinished CityJSON upload.

Inputs: upload_id (required).

cityjson_upload_chunkSend CityJSON upload chunkC

Send the next chunk from the CityJSON file picker.

Inputs: bytes (required), offset (required), upload_id (required).

cityjson_upload_finishFinish CityJSON uploadC

Validate and register the uploaded CityJSON file.

Inputs: upload_id (required).

cityjson_upload_startStart CityJSON uploadC

Start an upload from the CityJSON file picker.

Inputs: filename (required), size_bytes (required).

cityjson_validateValidate CityJSON completelyB

Run cjval and val3dity and return one combined structural + geometric validation result. geometry.reportSummary contains the complete invalidObjectIds list for reliable follow-up subsets.

Inputs: dataset_id (required).

cityjson_validate_geometryValidate 3D geometryB

Validate CityJSON 3D primitives with val3dity according to ISO 19107 concepts and CityJSON-specific geometric checks. Returns a detailed report plus a compact reportSummary containing every invalid object ID and error-code count.

Inputs: dataset_id (required), verbose.

cityjson_validate_schemaValidate CityJSON syntax and schemaB

Validate a dataset with the official cjval validator: JSON syntax, CityJSON schemas, extensions and additional structural consistency checks.

Inputs: dataset_id (required), extension_schemas.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 42 tools

    Disambiguation3/5

    Most tools target a distinct operation, but two clusters overlap heavily: the upload/import family (cityjson_upload, cityjson_upload_start, cityjson_upload_chunk/finish/cancel, cityjson_import, cityjson_import_text, cityjson_open, cityjson_list_imports) and the validation family (cityjson_validate, cityjson_validate_schema, cityjson_validate_geometry). Descriptions do provide guidance on when to use each, but an agent must read carefully to avoid misselection.

    Naming Consistency4/5

    All tools use a consistent snake_case cityjson_-prefixed verb_noun pattern (cityjson_validate_geometry, cityjson_subset, cityjson_reproject, etc.), which is highly predictable. A few exceptions are noun-only (cityjson_info, cityjson_download, cityjson_backend_status) but these remain readable and consistent in style.

    Tool Count2/5

    42 tools is heavy for the stated scope and pushes well past the 15-tool guideline, especially since much of the surface is protocol plumbing (upload chunk/finish/cancel) and redundant validation entry points. The set feels over-expanded rather than tightly scoped.

    Completeness4/5

    Coverage of the CityJSON lifecycle is strong: ingestion, validation, spatial/CRS transforms, geometry cleanup, subsetting, format conversion, DB import/export, querying, and spec/schema lookups are all present. Minor gaps exist around mutating object data—no attribute-set/add or object creation/deletion tools—but core workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Provides MCP tools for CPACS-oriented TiGL workflows, enabling lifecycle management, inspection, export, and parameter manipulation of aircraft geometry models without native geometry runtimes.
      11
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and software to create, edit, inspect, validate, and export CAD geometry through MCP using backend-neutral typed operations, with FreeCAD/OpenCascade as the authoritative B-rep backend and JSCAD preview.
      1
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for inspecting, analysing, and editing CityJSON and CityGML building datasets.
      19
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents and MCP clients to perform 3D asset creation and verification: exact b-rep CAD, GLB validation with embedded certificates, mesh inspection, and physics scenes, with most tools running without Blender.
      36
      48 npm
      MIT