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

🚀 Quick Start

Remote Server (Recommended)

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

<details> <summary>Cursor</summary>

Add to ~/.cursor/mcp.json:

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

</details>

<details> <summary>Claude Desktop</summary>

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"]
    }
  }
}

</details>

<details> <summary>VS Code</summary>

Add to your VS Code settings:

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

</details>

<details> <summary>Windsurf</summary>

Add to your Windsurf MCP config:

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

</details>

🔨 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

• CityJSON Official Website
• CityJSON Specification
• Model Context Protocol