# How the AI Element Filter Queries Revit Elements by Specific Criteria in revit-mcp

> Discover how the AI element filter in revit-mcp queries Revit elements by category type visibility and more without Revit API knowledge. Get precise data effortlessly.

- Repository: [MCP servers for Revit/revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The AI element filter provides a type-safe, JSON-RPC interface that allows AI assistants to query Revit elements by category, type, visibility, spatial bounds, and family parameters without requiring direct Revit API knowledge.**

The revit-mcp repository implements a Model Context Protocol (MCP) server that bridges AI assistants with Autodesk Revit. At the core of this integration sits the **AI element filter**, a sophisticated querying mechanism that translates high-level filter criteria into precise Revit API calls through a dynamic tool registration system and TCP socket communication.

## Architecture of the AI Element Filter

The implementation spans three distinct layers that handle discovery, validation, and execution. Understanding these layers reveals how the AI element filter maintains type safety while remaining flexible enough to support complex spatial and categorical queries.

### Dynamic Tool Registration

The server discovers the AI element filter automatically at startup through a dynamic registration system. In [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts), the server scans the `src/tools` directory, dynamically imports each module, and invokes any exported function whose name starts with `register`. For the AI element filter, this calls `registerAIElementFilterTool`, which binds the tool to the MCP server instance without requiring manual imports or static configuration.

### Type-Safe Schema Definition

The tool definition resides in [`src/tools/ai_element_filter.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/ai_element_filter.ts), where lines 10-70 declare a strict Zod schema that validates all incoming requests before they reach Revit. The `server.tool("ai_element_filter", …)` registration exposes the following optional filter parameters:

- **`filterCategory`** – Built-in Revit category such as `OST_Walls` or `OST_Floors`
- **`filterElementType`** – Element type name (class or database name) like `"Wall"`
- **`filterFamilySymbolId`** – Numeric `ElementId` of a specific family type
- **`includeTypes`** – Boolean to return type objects (wall types, door types); defaults to `false`
- **`includeInstances`** – Boolean to return placed instances; defaults to `true`
- **`filterVisibleInCurrentView`** – Restrict to elements visible in the active view (instances only)
- **`boundingBoxMin`** / **`boundingBoxMax`** – 3-D bounding box corners in millimeters; only elements intersecting the box are returned
- **`maxElements`** – Upper limit on results (default 50, values above 50 discouraged)

This schema ensures that malformed requests fail fast with clear validation errors before consuming Revit resources.

### Revit Communication Pipeline

When the AI element filter receives a valid request, the handler (lines 72-102) delegates execution to `withRevitConnection` from [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts). This utility manages the lifecycle of a `RevitClientConnection` implemented in [`src/utils/SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/SocketClient.ts).

The communication flow follows these steps:

1. **Socket Establishment** – `RevitClientConnection` opens a TCP socket to the Revit plug-in at `localhost:8080`
2. **JSON-RPC Serialization** – The client sends a request formatted as `{"method":"ai_element_filter","params":<args>}`
3. **Revit Execution** – The Revit side processes the request, executing the actual element query using the supplied filters against the Revit API
4. **Response Parsing** – The client parses the JSON result, which the tool handler formats as a pretty-printed JSON string (lines 84-89)
5. **Error Handling** – Socket errors or Revit exceptions are caught and reported as descriptive text messages (lines 91-99)

This pipeline provides a stateless, network-transparent interface that isolates the AI assistant from Revit API complexity while maintaining robust error handling.

## Querying Elements with the AI Element Filter

The AI element filter supports complex queries that combine categorical, typological, and spatial constraints. Understanding how these parameters interact helps construct efficient requests that minimize Revit processing time.

### Category and Type Filtering

Use `filterCategory` to target built-in Revit categories and `filterElementType` to narrow down to specific classes. For example, querying all wall instances in the current view:

```json
{
  "tool": "ai_element_filter",
  "arguments": {
    "filterCategory": "OST_Walls",
    "includeInstances": true,
    "filterVisibleInCurrentView": true,
    "maxElements": 20
  }
}

```

When the MCP server receives this payload, it executes the handler in [`ai_element_filter.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/ai_element_filter.ts), forwards the parameters to Revit via the socket connection, and returns a JSON array of wall instances.

### Spatial Bounding Box Queries

The `boundingBoxMin` and `boundingBoxMax` parameters enable 3-D spatial filtering using millimeter coordinates. This is particularly useful for retrieving elements within specific rooms or construction zones:

```typescript
import { withRevitConnection } from "./utils/ConnectionManager.js";

async function getFurnitureInZone() {
  const params = {
    filterCategory: "OST_Furniture",
    boundingBoxMin: { p0: { x: 0, y: 0, z: 0 }, p1: { x: 0, y: 0, z: 0 } },
    boundingBoxMax: { p0: { x: 5000, y: 5000, z: 3000 }, p1: { x: 5000, y: 5000, z: 3000 } },
    includeInstances: true,
    maxElements: 50,
  };

  const elements = await withRevitConnection(client =>
    client.sendCommand("ai_element_filter", params)
  );

  console.log("Found furniture:", elements);
}

```

This request returns all furniture elements whose geometry intersects the defined 5 m × 5 m × 3 m bounding box, demonstrating how the AI element filter combines categorical and spatial constraints.

### Direct Tool Invocation

For custom server logic or testing, invoke the tool directly through the connection manager:

```typescript
import { withRevitConnection } from "./utils/ConnectionManager.js";

async function getWalls() {
  const params = {
    filterCategory: "OST_Walls",
    includeInstances: true,
    maxElements: 10,
  };

  const elements = await withRevitConnection(client =>
    client.sendCommand("ai_element_filter", params)
  );

  console.log("Found walls:", elements);
}

```

This pattern bypasses the MCP tool layer while maintaining the same validation and communication infrastructure.

## Summary

The **AI element filter** in revit-mcp provides a robust, type-safe bridge between AI assistants and Revit element databases:

- **Dynamic registration** via [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts) automatically discovers the tool at server startup without manual configuration
- **Strict validation** through Zod schemas in [`src/tools/ai_element_filter.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/ai_element_filter.ts) prevents malformed requests from reaching Revit
- **Network-transparent execution** using `withRevitConnection` and `RevitClientConnection` manages TCP sockets to the Revit plug-in at `localhost:8080`
- **Comprehensive filtering** supports categorical (`filterCategory`, `filterElementType`), typological (`includeTypes`, `includeInstances`), visibility (`filterVisibleInCurrentView`), and spatial (`boundingBoxMin`, `boundingBoxMax`) constraints
- **Safe defaults** limit results to 50 elements by default, with clear error handling for socket failures and Revit exceptions

## Frequently Asked Questions

### What is the default limit for elements returned by the AI element filter?

The **AI element filter** defaults to returning **50 elements** via the `maxElements` parameter. The implementation discourages values above 50 to prevent performance degradation in Revit, though you can request fewer elements (e.g., 10 or 20) for faster response times when testing queries.

### How does the AI element filter handle spatial queries with bounding boxes?

The filter accepts `boundingBoxMin` and `boundingBoxMax` parameters defined in **millimeters**, each containing `p0` and `p1` coordinate objects. When provided, the Revit plug-in performs a 3-D intersection test, returning only elements whose geometry intersects the defined volume. This enables room-specific or zone-based queries without requiring the AI to understand Revit geometry APIs.

### Can the AI element filter return both type definitions and instances simultaneously?

Yes, by setting both `includeTypes` to `true` and `includeInstances` to `true`, the query returns both category-specific type objects (like wall types or door types) and their placed instances in the model. By default, `includeInstances` is `true` and `includeTypes` is `false`, optimizing for common use cases where only placed elements are needed.

### What happens if Revit is not running when the AI element filter is invoked?

If the Revit plug-in is not listening on `localhost:8080`, the `withRevitConnection` utility in [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) will fail to establish the TCP socket. The error handler (lines 91-99 in [`ai_element_filter.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/ai_element_filter.ts)) catches this exception and returns a descriptive text message to the AI assistant, indicating that the Revit connection is unavailable rather than crashing the server or returning empty results.