How do I use TopologicPy MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TopologicPy MCP Server Create a 3-storey building 12m x 20m with 3.5m floor heights" 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.

TopologicPy MCP Server

A Model Context Protocol server that exposes TopologicPy TopologicPy-docs's spatial modeling capabilities to LLM agents like Claude Code, Claude Desktop, and other MCP clients. This was created to assist us in developing further tools around Topologic and TopologicPy

What This Enables

Ask Claude (or any MCP-equipped LLM) to build architectural models through natural language:

"Create a 3-storey office building, 12m × 20m with 3.5m floor heights, then show me the adjacency graph and export to IFC"

The MCP server translates these requests into precise TopologicPy operations, maintaining a named object session across the conversation.

Architecture

┌─────────────────────────────────────────────────┐
│              MCP Client (Claude Code, etc.)       │
│  Natural language ↔ tool calls                   │
└────────────────────┬────────────────────────────┘
                     │  MCP Protocol (stdio/SSE)
                     ▼
┌─────────────────────────────────────────────────┐
│            TopologicPy MCP Server                │
│  ┌───────────────────────────────────────────┐  │
│  │  Session Store (named topology objects)    │  │
│  │  • "building" → CellComplex               │  │
│  │  • "floor_0"  → Cell                      │  │
│  │  • "graph"    → Graph                     │  │
│  └───────────────────────────────────────────┘  │
│                                                  │
│  Tools: create, boolean, transform, query, I/O   │
│  Resources: session state, BREP strings          │
│  Prompts: building envelope, adjacency, grids    │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│                  TopologicPy                     │
│  Vertex → Edge → Wire → Face → Shell → Cell     │
│  CellComplex → Cluster → Graph → Dictionary     │
│  OpenCASCADE (BREP) • IfcOpenShell (IFC)        │
└─────────────────────────────────────────────────┘

Available Tools (36 tools)

Creation

Tool	Description
`create_vertex`	Create a point at (x, y, z)
`create_edge`	Line segment between two vertices
`create_wire`	Polyline from ordered vertices
`create_face_by_wire`	Face from a closed wire
`create_face_rectangle`	Rectangular face
`create_face_circle`	Circular face (polygon approximation)
`create_cell_by_faces`	3D solid from bounding faces
`create_cell_prism`	Box / rectangular prism
`create_cell_cylinder`	Cylindrical cell
`create_cellcomplex_by_cells`	Merged cell assembly (shared boundaries)
`create_cluster`	Unstructured collection

Boolean Operations

Tool	Description
`boolean_union`	A ∪ B
`boolean_difference`	A − B
`boolean_intersect`	A ∩ B
`self_merge`	Resolve self-intersections

Transformations

Tool	Description
`translate`	Move by vector
`rotate`	Rotate around axis
`scale`	Scale relative to origin

Query & Analysis

Tool	Description
`list_topologies`	List all named objects in session
`query_topology`	Detailed info (counts, centroid, volume, area)
`get_vertices`	Extract vertex coordinates
`get_sub_topologies`	Extract and optionally store sub-elements

Graph Operations

Tool	Description
`create_graph_from_topology`	Dual/adjacency graph
`graph_shortest_path`	Shortest path between vertices

Dictionary (Metadata)

Tool	Description
`set_dictionary`	Attach key-value metadata
`get_dictionary`	Read attached metadata

Import / Export

Tool	Description
`export_brep`	Export to BREP string/file
`import_brep`	Import from BREP string/file
`export_obj`	Export triangulated mesh (OBJ)
`export_ifc`	Export to IFC (BIM)
`import_ifc`	Import from IFC file

Session Management

Tool	Description
`remove_topology`	Delete from session
`rename_topology`	Rename an object
`copy_topology`	Deep copy with new name

Installation

With uv (recommended)

cd topologic-mcp-server
uv venv
source .venv/bin/activate
uv pip install -e .

With pip

cd topologic-mcp-server
pip install -e .

Usage

With Claude Code

Add to your Claude Code MCP configuration (~/.claude/claude_code_config.json):

{
  "mcpServers": {
    "topologic": {
      "command": "python",
      "args": ["-m", "topologic_mcp"],
      "cwd": "/path/to/topologic-mcp-server"
    }
  }
}

Or using uv directly:

{
  "mcpServers": {
    "topologic": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/topologic-mcp-server", "topologic-mcp"]
    }
  }
}

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "topologic": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/topologic-mcp-server", "topologic-mcp"]
    }
  }
}

Standalone (stdio transport)

python -m topologic_mcp

With MCP Inspector (for testing)

mcp dev src/topologic_mcp/server.py

Example Conversations

Create a simple building

User: Create a 3-storey building, 10m × 15m, 3m floor height

Claude: [calls create_vertex, create_cell_prism × 3, translate × 2,
         create_cellcomplex_by_cells, query_topology]

Result: CellComplex "building" with 3 cells, 16 faces, 33 edges, 20 vertices

Analyze spatial adjacency

User: Show me which floors share faces in the building

Claude: [calls create_graph_from_topology with via_shared_faces=True,
         get_sub_topologies to list cells, query each cell]

Result: Graph with 3 vertices (one per floor) and 2 edges
        (floor_0↔floor_1, floor_1↔floor_2)

Boolean operations

User: Cut a 2m diameter hole through the middle of floor_1

Claude: [calls create_cell_cylinder for the hole, translate to position,
         boolean_difference to subtract from floor_1]

Result: Updated floor_1 with cylindrical void

License

GPL-3.0-or-later (matching TopologicPy's license)

Contributing

This server wraps TopologicPy's pure-Python API. To add new tools:

Add a @mcp.tool() decorated function in server.py
Follow the naming convention: verb_noun (e.g., create_vertex, export_brep)
Always accept ctx: Context as the first parameter
Use the TopologyStore from ctx.request_context.lifespan_context
Return descriptive strings (the LLM reads these)

TopologicPy MCP Server

TopologicPy MCP Server

What This Enables

Architecture

Available Tools (36 tools)

Creation

Boolean Operations

Transformations

Query & Analysis

Graph Operations

Dictionary (Metadata)

Import / Export

Session Management

Installation

With uv (recommended)

With pip

Usage

With Claude Code

With Claude Desktop

Standalone (stdio transport)

With MCP Inspector (for testing)

Example Conversations

Create a simple building

Analyze spatial adjacency

Boolean operations

License

Contributing

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API