cityjson-mcp
This server gives an AI assistant a full CityJSON toolkit: import, inspect, query, validate, transform, export, convert, and database-store 3D city model datasets.
Check backends — report which external engines (cjio, cjval, val3dity, citygml-tools, cjdb) are installed and callable.
Get data in — open a project file by name/path, import from the input inbox, import a small CityJSON text, or use the in-chat chunked file picker upload.
Inspect and query — return version, counts, types, LoDs, attributes, transform and extensions; list CityObjects with pagination and type filters; fetch one object with its real-world bounding box; query by IDs, types, 2D bbox and attribute predicates (eq, neq, gt, gte, lt, lte, contains, in).
Validate — syntax/schema/extension checks via cjval, 3D geometry checks via val3dity, or both in one combined result with invalid object IDs.
Transform — subset (IDs, bbox, radius, random, types, exclude), filter LoD, reproject, assign CRS, translate, clean vertices, triangulate, merge datasets, rename/remove attributes, strip textures or materials, upgrade CityJSON version.
Export and convert — export to jsonl, obj, stl, glb or b3dm; convert CityGML→CityJSON/CityJSONSeq and CityJSON→CityGML.
Database — import datasets into PostgreSQL/PostGIS via cjdb and export all objects or a read-only SELECT subset back to CityJSONSeq/CityJSON.
Deliver results — save a dataset to an authorized destination or prepare it for download.
Reference docs — read the bundled CityJSON spec outline, fetch the living spec, read canonical JSON Schemas, and browse or read registered extension schemas.
Provides CityJSON import and export to PostgreSQL/PostGIS, enabling database storage and retrieval of CityJSON datasets via cjdb.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cityjson-mcp Validate the 3D geometry of a CityJSON file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
cjiofor CityJSON transformations and export.cjvalfor syntax, schema, and structural validation.val3dityfor 3D geometry validation.citygml-toolsfor CityGML and CityJSON conversion.cjdbfor 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.

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 install2. Create .env
Copy the example file:
cp .env.example .envSet 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.1The model settings mean:
Variable | Required | Description |
| yes | Model service: |
| yes | Exact model identifier sent to the provider, for example |
| except Ollama | API credential issued by the model provider. Local Ollama needs no key. Do not commit |
| yes | Base URL for the provider API. |
| no | Sampling temperature. Datum defaults to |
| no | Ollama context window in tokens. Defaults to |
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.
Recommended free cloud models through OpenRouter
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.1This 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/v1GPT-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.
Recommended cloud configurations
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-ollamaFor 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 |
| Example model |
|
Ollama |
|
|
|
OpenRouter |
| select a model that supports tools from the live catalog |
|
Google Gemini |
|
|
|
DeepSeek |
|
|
|
OpenAI GPT |
| a current GPT model with Chat Completions tool calling |
|
Anthropic Claude |
| a current Claude model with tool use |
|
Model names and availability change. Confirm the exact model identifier in the provider documentation:
3. Start Datum
npm run chatOpen 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:stopnpm run chat uses this sequence to select images:
Read
.envand resolve Ollama mode from--with-ollama,--without-ollama,CHAT_ENABLE_OLLAMA, orMODEL_PROVIDER, in that order.Print whether startup uses a cloud model, native Ollama, or bundled Ollama.
If Ollama is enabled on macOS, use a running native service when detected; otherwise pull the official Ollama image only when it is missing.
Check whether the CityJSON MCP image exists and pull it when missing.
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 chatThe 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.mjsThe 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.jsonWindows:
%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.jsonRestart 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.jsonGlobal:
~/.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:latestAdd 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 --> KNOWTool 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 |
| native | Report backend availability and path settings. |
| native | List JSON files in the input directory. |
| native | Register a file delivered to Datum's input inbox. |
| native | Show a file picker in the chat and upload directly to the MCP server. |
| native | Import a small CityJSON document supplied as text. |
| native | Open a project file by name or path and snapshot it. |
| native | Return a source or derived CityJSON file. |
| native | Copy a dataset to an authorized destination. |
| native | Return version, counts, LoDs, attributes, metadata, transform, and extensions. |
| native | List CityObjects with pagination and type filters. |
| native | Return one CityObject and its computed bounding box. |
| native | Query by IDs, types, bounding box, and attribute predicates. |
Validation
Tool | Backend | Purpose |
| cjval | Validate JSON syntax, schemas, extensions, and structural consistency. |
| val3dity | Validate supported 3D geometry primitives. |
| 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 |
| cjio | Select or exclude objects by IDs, type, bounding box, radius, or random count. |
| cjio | Keep one level of detail. |
| cjio | Transform coordinates to a target EPSG CRS. |
| cjio | Assign an EPSG CRS without changing coordinates. |
| cjio | Translate coordinates. |
| cjio | Remove duplicate and unused vertices. |
| cjio | Triangulate surfaces. |
| cjio | Merge two or more datasets. |
| cjio | Rename an attribute. |
| cjio | Remove an attribute. |
| cjio | Remove textures. |
| cjio | Remove materials. |
| cjio | Upgrade an older supported CityJSON version. |
Export, conversion, and database
Tool | Backend | Purpose |
| cjio | Export to JSONL, OBJ, STL, GLB, or B3DM. |
| citygml-tools | Convert CityGML to CityJSON or CityJSONSeq. |
| citygml-tools | Convert CityJSON to CityGML. |
| cjio + cjdb | Import a dataset into PostgreSQL/PostGIS. |
| cjdb + cjio | Export all or selected objects from cjdb. |
Specification and schemas
Tool | Source | Purpose |
| bundled index | Return the CityJSON specification outline and schema names. |
| cityjson.org | Read part of the CityJSON specification. |
| cityjson.org | Read a CityJSON JSON Schema. |
| CityJSON registry | List or search registered extensions. |
| 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 astile-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 service: |
| none | Default Datum model identifier. |
| none | Default Datum model API key. |
| provider default | Model API base URL. |
|
| Maximum output tokens per model call. |
|
| Model sampling temperature. |
| automatic | Start bundled/native Ollama with Datum. When unset, enabled only for |
|
| Datum bind address outside Docker. |
|
| Datum port. |
|
| Maximum upload size. |
|
| Maximum files per upload. |
|
| Maximum rounds of tool calls per response. |
| current directory | Authorized filesystem roots. Use |
|
| Input directory used by |
|
| Managed source and derived datasets. |
|
| External command timeout. |
|
| Maximum file size for the CityJSON picker in the chat. |
|
| Maximum inline MCP download size. Datum streams downloads directly. |
|
| Optional cjio executable override. |
|
| Optional cjval executable override. |
|
| Optional val3dity executable override. |
|
| Optional citygml-tools executable override. |
|
| Optional cjdb executable override. |
Set PGPASSWORD in the process environment for cjdb. Database tool arguments do not accept a password.
Run without Docker (not recommended)
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 startInstall 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
.dmgfrom the official Ollama download page, move Ollama to Applications, and launch it. macOS 14 or newer is required.Windows: download and run
OllamaSetup.exefrom the official Ollama download page. Ollama starts in the background and exposes its API on port11434.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/tagsFor 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=16384Then 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
SELECTstatement, 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
Fork the repository and create a branch for one change.
Install dependencies with
npm install.Make the change. Keep MCP tool inputs typed and do not run shell commands from strings.
Add or update tests for changed behavior.
Run:
npm test npm run checkIf the change affects a Docker backend, build the image and run
npm run docker:doctor.Update the README and
.env.examplewhen configuration or behavior visible to users changes.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 testRun syntax checks for project .mjs files:
npm run checkVerify every executable in the Docker image:
npm run docker:doctorKnown 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_querycomputes 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.
val3dityis 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 specification: Official CityJSON specification and documentation.
CityJSON specification repository: Source repository for the CityJSON specification.
CityJSON Extensions registry: Registry of CityJSON extensions maintained by the community.
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
Model Context Protocol TypeScript SDK: TypeScript SDK for implementing Model Context Protocol servers and clients.
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 toolscitygml_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
Scored across 42 tools
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.
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.
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.
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
Related MCP Connectors
Geometry and CAD file metadata extraction for STL, OBJ, PLY, PCD, LAS/LAZ, glTF/GLB.
Global CAD/BIM, industrial engineering (FEM, CFD) and property tools via one MCP endpoint.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- AlicenseBqualityBmaintenanceProvides MCP tools for CPACS-oriented TiGL workflows, enabling lifecycle management, inspection, export, and parameter manipulation of aircraft geometry models without native geometry runtimes.113MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1Apache 2.0
- AlicenseAqualityCmaintenanceMCP server for inspecting, analysing, and editing CityJSON and CityGML building datasets.19Apache 2.0
- AlicenseAqualityCmaintenanceEnables 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.3648 npmMIT