Skip to main content
Glama
CityJSON Specification MCP Server

CityJSON Specification MCP Server

Official
by cityjson

CityJSON Specification MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with structured access to the CityJSON specification. Instead of feeding entire specifications to LLMs, this server enables AI to fetch specific chapters on demand.

šŸ“ŗ Demo

https://github.com/user-attachments/assets/91f0bd61-a313-441c-8def-4e07b8d125be

Related MCP server: web-ui-component-spec-mcp

šŸš€ Quick Start

Connect directly to the hosted server - no installation required:

https://your-cloud-run-url.run.app/mcp

Alternatively, use the community-hosted instance (subject to availability and resource constraints):

https://cj-mcp-264879243442.europe-west4.run.app/mcp

Local Installation

Run locally using npx:

npx @cityjson/cj-mcp@latest

Or install globally:

npm install -g @cityjson/cj-mcp@latest
cityjson-spec-mcp

šŸ› ļø Installation

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cityjson-spec": {
      "command": "npx",
      "args": ["-y", "@cityjson/cj-mcp@latest"]
    }
  }
}

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "cityjson-spec": {
      "command": "npx",
      "args": ["-y", "@cityjson/cj-mcp@latest"]
    }
  }
}

Add to your VS Code settings:

{
  "mcp": {
    "servers": {
      "cityjson-spec": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@cityjson/cj-mcp@latest"]
      }
    }
  }
}

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "cityjson-spec": {
      "command": "npx",
      "args": ["-y", "@cityjson/cj-mcp@latest"]
    }
  }
}

šŸ”Ø Available Tools

cityjson_read_spec_outline

Returns the specification outline with all chapters and sections.

Parameters:

  • include_sections (boolean, optional): Include section headings within each chapter. Default: true

Example Response:

{
  "version": "2.0.1",
  "total_chapters": 12,
  "chapters": [
    {
      "id": "introduction",
      "title": "Introduction",
      "order": 1,
      "sections": ["overview", "design-goals", "file-extension"]
    }
  ]
}

cityjson_read_spec_chapter

Returns the full Markdown content for a specific chapter.

Parameters:

  • chapter (string, required): Chapter identifier (e.g., "metadata", "city-objects")

Example:

{
  "chapter": "metadata"
}

šŸ’» Development

# Clone with submodules
git clone --recurse-submodules https://github.com/cityjson/cityjson-spec-mcp.git
cd cityjson-spec-mcp

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Convert specification (requires uv/bikeshed)
pnpm convert-spec

# Start MCP server (stdio mode)
pnpm start:stdio

# Start MCP server (HTTP mode)
pnpm start:http

# Lint and format
pnpm lint
pnpm lint:fix

šŸ“¦ Project Structure

cityjson-spec-mcp/
ā”œā”€ā”€ packages/
│   ā”œā”€ā”€ spec-converter/     # Bikeshed → Markdown converter
│   └── mcp-server/         # MCP server implementation
ā”œā”€ā”€ specs/                  # Generated specification files
│   ā”œā”€ā”€ index.json          # Chapter metadata index
│   └── chapters/           # Individual chapter Markdown files
ā”œā”€ā”€ vendor/
│   └── cityjson-specs/     # Git submodule (CityJSON spec repo)
└── Dockerfile              # Container for Cloud Run deployment

šŸ“„ License

MIT

šŸ”— Resources

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers