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

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 and src/tools/operate_element.ts, tools are registered using a consistent pattern. The modify_element tool, defined in src/tools/modify_element.ts, follows this same registration template:

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, which validates incoming payloads using zod schemas. Before executing any command, the withRevitConnection utility in 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, 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 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:

{
  "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:

{
  "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 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:

{
  "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):

{
  "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:

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 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	Placeholder for the registerModifyElementTool function that defines the tool schema and handler (follows the pattern of delete_element.ts).
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	Demonstrates zod schema validation patterns for tool arguments.
src/tools/register.ts	Central registry where all tools including modify_element are initialized with the MCP server instance.
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	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 (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 for socket health, SocketClient.ts for JSON-RPC transmission, and follows the registration pattern seen in 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 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}