CityEngine Cloud MCP Server & Tools

Text-to-3D city buildings in one sentence: natural language → CGA rules → cloud engine → glTF/glb — plus demo browsing and quota lookup. Read-only compute endpoints only.

This repository contains two complementary packages:

Package	What it is	Use it with
cityengine-mcp (repo root)	MCP server (stdio, FastMCP)	kimi code, Codex CLI, Claude Desktop, any MCP client
cityengine-tools/	OpenAI-compatible function-calling toolkit (schemas + client)	DeepSeek, Qwen, GLM, GPT and any OpenAI-style tool-calling API

Live demos and self-service API keys: https://www.cityengine.cn/plugins.html · API contract: https://api.cityengine.cn

Tools (6)

Tool	Description	Quota
generate_cga	Natural language → CGA rule source (sync, no rendering); supports base_cga + instruction refinement	NL quota
parse_cga	CGA source + attributes → engine parse → 3D model stats + glb download (sha256 verified)	generate quota
generate_model	Natural language → ready 3D model (NL2CGA + parse chained), returns cga_source too	NL + generate
list_demos	List showcase demos on the official site (id/name/engine/attribute count)	free
get_demo	Inspect a demo's attribute panel, node/material counts, engine timing	free
get_quota	Current key's plan and quota usage	free

All endpoints are read-only compute calls — nothing writes to your account or the site.

Install (MCP server)

pip install cityengine-mcp        # or: pip install .  from this repo
# provides the `cityengine-mcp` console script; or run: python -m cityengine_mcp.server

Requirements: Python ≥ 3.10, mcp 1.x, httpx.

Get an API key

Keys use the cvk_ prefix. Two self-service ways:

1. Website: register/log in at https://www.cityengine.cn → User Center → "插件 Key" → issue (shown once, save it).
2. CLI:

curl -X POST https://api.cityengine.cn/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"strong-password","nickname":"optional"}'
# the response api_key is your plugin key (shown in full only once)

Free tier: 5 NL generations/month, 100 model generations/day. Paid members: unlimited NL.

Configure your MCP client

Environment variables:

Variable	Required	Default	Purpose
CITYENGINE_API_KEY	yes	—	plugin API key (cvk_…)
CITYENGINE_GATEWAY_BASE	no	https://api.cityengine.cn	gateway base URL
CITYENGINE_DEMOS_BASE	no	https://www.cityengine.cn	demo listing site
CITYENGINE_OUTPUT_DIR	no	./cityengine_mcp_output	where glb files land
CITYENGINE_MAX_POLL_S	no	300	render job poll cap (seconds)

Generic MCP client config:

{
  "mcpServers": {
    "cityengine": {
      "command": "python",
      "args": ["-m", "cityengine_mcp.server"],
      "env": { "CITYENGINE_API_KEY": "cvk_xxx" }
    }
  }
}

Ready-made snippets for kimi code, Codex CLI and Claude Desktop live in config-examples/.

OpenAI-compatible function calling (cityengine-tools/)

pip install ./cityengine-tools

from cityengine_tools import CityEngineTools
tools = CityEngineTools(api_key="cvk_xxx")
# pass tools.schemas() as the `tools` parameter of any OpenAI-compatible chat call;
# feed tool_calls back into tools.dispatch(...) to execute them.

JSON schemas for all six tools are in cityengine-tools/schemas/.

Links

• Website & demos: https://www.cityengine.cn · plugin page: https://www.cityengine.cn/plugins.html
• API: https://api.cityengine.cn (OpenAPI contract openapi-v1.yaml)

License

MIT (see LICENSE). The packages are client SDKs; generated models and CGA output are governed by your cityengine.cn plan terms.