# How to Modify Element Instance Parameters Using the revit-mcp modify_element Tool

> Learn to modify element instance parameters in Revit using the revit-mcp modify_element tool. Update parameters via JSON-RPC commands for AI assistants and automation.

- 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 `modify_element` tool in revit-mcp enables AI assistants and automation scripts to update Revit element instance parameters by sending JSON-RPC commands through a TCP socket connection to the Revit plugin.**

The revit-mcp repository provides a Model Context Protocol (MCP) server that bridges large language models with Autodesk Revit. By leveraging the `modify_element` tool, developers can programmatically modify element instance parameters without directly interacting with the Revit API, streamlining automation workflows and AI-driven design modifications.

## Understanding the modify_element Tool Architecture

The `modify_element` tool follows a layered architecture that abstracts the complexity of Revit's native API behind a simple JSON interface.

### Tool Registration Pattern

According to the source code in [`src/tools/delete_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/delete_element.ts) and [`src/tools/operate_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/operate_element.ts), tools are registered using a consistent pattern. The `modify_element` tool, defined in [`src/tools/modify_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/modify_element.ts), follows this same registration template:

```typescript
export function registerModifyElementTool(server: McpServer) {
  server.tool(
    "modify_element",
    "Modify element's properties (instance parameters)",
    {
      // Zod schema for validation
    },
    async (args, extra) => {
      const params = args;
      const response = await withRevitConnection(async (client) => {
        return await client.sendCommand("modify_element", params);
      });
      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
    }
  );
}

```

### MCP Server and Connection Flow

The tool integrates with the MCP server through [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts), which validates incoming payloads using **zod** schemas. Before executing any command, the `withRevitConnection` utility in [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) ensures an active TCP socket connection to the Revit plugin. The actual JSON-RPC transmission occurs through [`src/utils/SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/SocketClient.ts), which packages the method name (`modify_element`) and parameters into a structured payload.

## Data Contract and Parameter Schema

To successfully modify element instance parameters, the tool expects a specific JSON structure. As documented in the repository's [`README.md`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/README.md) at line 103, the tool specifically targets **instance parameters** (not type parameters).

The data contract consists of:

- **`elementIds`**: An array of integers representing Revit ElementIds to update
- **`parameters`**: An array of objects, each containing:
  - `name`: The exact parameter name as it appears in Revit (e.g., `"Width"`, `"Comments"`, `"Mark"`)
  - `value`: The new value (string, number, boolean, or integer depending on the parameter's storage type)

The Revit plugin validates that each parameter is an instance parameter and that the provided value matches the parameter's storage type (String, Double, Integer, or Boolean).

## Practical Code Examples for Modifying Instance Parameters

The following examples demonstrate how to structure payloads for the `modify_element` tool in real-world scenarios.

### Single Parameter Update

To update the Comments field on a single wall or door element:

```json
{
  "tool": "modify_element",
  "arguments": {
    "elementIds": [123456],
    "parameters": [
      { "name": "Comments", "value": "Updated by revit-mcp" }
    ]
  }
}

```

The Revit plugin locates element `123456`, writes `"Updated by revit-mcp"` into its **Comments** instance field, and returns a confirmation object such as `{ success: true, updated: 1 }`.

### Batch Updates Across Multiple Elements

Efficiently apply the same parameter values to multiple elements in a single round-trip:

```json
{
  "tool": "modify_element",
  "arguments": {
    "elementIds": [10101, 10102, 10103],
    "parameters": [
      { "name": "Mark", "value": "A-01" },
      { "name": "FireRating", "value": 2 }
    ]
  }
}

```

All three elements receive the same **Mark** and **FireRating** values in one round-trip, which is far more efficient than invoking the tool three times. The [`ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/ConnectionManager.ts) ensures the socket remains open for this batch operation.

### Mixed Data Type Modifications

Revit parameters accept various storage types. This example updates Boolean, numeric, and string parameters simultaneously:

```json
{
  "tool": "modify_element",
  "arguments": {
    "elementIds": [55555],
    "parameters": [
      { "name": "IsExternal", "value": true },
      { "name": "Thickness", "value": 300 },
      { "name": "Manufacturer", "value": "Acme Corp." }
    ]
  }
}

```

The Revit API automatically casts these JSON primitives to the appropriate `StorageType` (Boolean, Double, String) before calling `SetParameterValueByName` on the instance parameters.

**Typical response** (pretty-printed by the tool):

```json
{
  "success": true,
  "updatedElements": 1,
  "details": [
    { "elementId": 55555, "modifiedParameters": ["IsExternal", "Thickness", "Manufacturer"] }
  ]
}

```

### TypeScript Client Implementation

For custom integrations using the MCP SDK, invoke the tool programmatically:

```typescript
import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";

const client = new McpClient({ url: "ws://localhost:8000" });

await client.callTool("modify_element", {
  elementIds: [20001],
  parameters: [{ name: "Length", value: 4500 }]
});

```

The client library serializes the same JSON payload under the hood and returns the parsed response. The [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) handles the underlying TCP communication with the Revit plugin.

## Key Source Files and Implementation Details

Understanding the codebase helps troubleshoot connection issues or extend functionality. The `modify_element` tool relies on the following critical files:

| File | Purpose |
|------|---------|
| [`src/tools/modify_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/modify_element.ts) | Placeholder for the `registerModifyElementTool` function that defines the tool schema and handler (follows the pattern of [`delete_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/delete_element.ts)). |
| [`src/tools/delete_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/delete_element.ts) | Reference implementation showing how tools register with the MCP server and forward commands to Revit. |
| [`src/tools/operate_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/operate_element.ts) | Demonstrates **zod** schema validation patterns for tool arguments. |
| [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts) | Central registry where all tools including `modify_element` are initialized with the MCP server instance. |
| [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) | Singleton that manages TCP socket lifecycle, ensuring `withRevitConnection` blocks until a healthy connection to the Revit plugin exists. |
| [`src/utils/SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/SocketClient.ts) | Low-level JSON-RPC client that packages the `modify_element` command and payload into a TCP message and parses the Revit plugin's response. |
| [`README.md`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/README.md) (line 103) | Official documentation confirming that `modify_element` targets **instance parameters** specifically. |

## Summary

- The `modify_element` tool in revit-mcp provides a JSON-RPC interface for updating Revit element instance parameters without direct API coding.
- It requires an array of `elementIds` and a `parameters` array containing `{name, value}` pairs matching Revit's instance parameter names.
- The architecture relies on [`ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/ConnectionManager.ts) for socket health, [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) for JSON-RPC transmission, and follows the registration pattern seen in [`delete_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/delete_element.ts).
- Batch updates across multiple elements and mixed data types (string, number, boolean) are supported in a single call, optimizing network efficiency.

## Frequently Asked Questions

### What is the difference between instance and type parameters in revit-mcp?

Instance parameters belong to individual Revit elements (like a specific wall or door), allowing each element to have unique values. Type parameters belong to family types and change all instances of that type simultaneously. According to the [`README.md`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/README.md) at line 103, the `modify_element` tool specifically targets instance parameters, not type parameters. To modify type parameters, you would need a different workflow or tool.

### Can I modify multiple parameters on multiple elements in a single call?

Yes. The `modify_element` tool accepts an array of `elementIds` and an array of `parameters` objects. You can specify multiple element IDs (e.g., `[10101, 10102, 10103]`) and multiple parameter updates (e.g., updating both `Mark` and `FireRating`) in a single JSON payload. This batch approach minimizes network overhead by sending one command through the [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) connection rather than multiple individual requests.

### What data types are supported for parameter values?

The tool supports all Revit storage types through JSON primitives. You can pass strings for text parameters, numbers (integers or floats) for dimensional or numeric parameters, and booleans for yes/no parameters. The Revit plugin validates that the provided value matches the parameter's `StorageType` (String, Double, Integer, or Boolean) before calling `SetParameterValueByName`. If type mismatches occur, the Revit plugin returns an error in the JSON-RPC response.

### How does the tool handle invalid element IDs or parameter names?

The Revit plugin performs validation after receiving the JSON-RPC command via [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts). If an element ID does not exist in the current document, or if a parameter name does not match an instance parameter on that element, the plugin returns a structured error response. The `modify_element` tool forwards this response back to the client, typically including fields like `success: false` and an error message detailing which element or parameter failed validation. Always verify element IDs through the `get_element_info` tool or similar before attempting modifications.