MCP Server

Overview

Beaver can act as an MCP (Model Context Protocol) server. MCP is the protocol that AI
clients such as Claude Code and Claude Desktop use to call the features of another
program. When the server is running, the AI can ask the running Beaver what is open,
list its commands and system variables, read the command pane, look up IFC entities,
and have Beaver save a picture of the current view. With writing allowed it can also
run commands and edit the model itself Eadding IFC entities, changing their
attributes, and undoing what it did.

The server runs inside Beaver.exe itself. There is no separate program to install and
no COM registration, so it works whether or not the COM API is available.

The server is off by default, and it only listens on the loopback address
(127.0.0.1), so nothing outside your own machine can reach it.

Turning it on

There are two ways.

Type _CliCmdMcpServer in the command pane. This starts the server for the current
session and prints the address it is listening on.
Set the system variable MCPSERVER to ON. The server then starts automatically
every time Beaver starts.

The command pane shows a line like this when the server starts:

The MCP server is listening on http://127.0.0.1:8765/mcp (loopback only, read-only).

System variables

Name	Default	Meaning
`MCPSERVER`	OFF	Start the server automatically when Beaver starts.
`MCPSERVERPORT`	8765	The port to listen on. If it is already in use, the next ports (up to +9) are tried, which lets you run more than one Beaver at a time.
`MCPSERVERTIMEOUT`	30	How many seconds a request waits for Beaver to become free. `0` means wait forever. Increase it if you drive a command that takes a long time.
`MCPSERVERALLOWWRITE`	OFF	Allow tools that change the drawing or the application. While this is OFF, such tools are neither listed nor executed.

Change them with the setvar command, or from Options.

Connecting a client

The server speaks MCP over HTTP. Point your client at the address printed in the
command pane. For Claude Code, put a file named .mcp.json in the folder you work in:

{
  "mcpServers": {
    "beaver": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Start Beaver and the server first, then start the client. If Beaver is not running the
client simply fails to connect; start Beaver and reconnect.

The port actually in use is also written to
%LOCALAPPDATA%\BIM VILLAGE\Beaver\mcp.json, which is useful when several instances of
Beaver are running and the port has been shifted.

What the AI can read

These tools are always available. None of them change your drawing.

Tool	What it does
`beaver_status`	Which drawings are open, which one is active, and whether Beaver is busy or waiting for input.
`beaver_list_commands`	Every command Beaver accepts, with its summary and aliases.
`beaver_get_output`	The text in the command pane, so the AI can read the result of what it just did.
`beaver_list_sysvals`	All system variables with their current values.
`beaver_get_sysval`	One system variable.
`beaver_get_model_summary`	The whole drawing at a glance: schema, length unit, the project, its sites, buildings and storeys with their elevations, and how many of each kind of element it holds.
`beaver_list_entity_types`	Every IFC type that is actually present, with counts.
`beaver_get_spatial_structure`	The project ↁEsite ↁEbuilding ↁEstorey tree, and what sits on each storey.
`beaver_find_instances`	Find IFC/STEP entities by type name, for example `IfcWall` or `IfcColumn`.
`beaver_get_instance`	One entity with its attributes.
`beaver_get_properties`	An element’s property sets, expanded Ethe information a drawing carries beyond its shape, such as whether a wall is external or load bearing.
`beaver_get_quantities`	An element’s quantities (length, area, volume, weight) as written in the file.
`beaver_get_placement`	Where an element sits in the building, and roughly how big it is.
`beaver_get_selection`	The elements you have selected on screen right now.
`beaver_get_document_info`	The drawing as a file: its path, IFC schema, whether it has unsaved edits, and the header saying which application wrote it.

beaver_get_selection is what makes “what is this?” work: select something in Beaver,
ask the question, and the AI can look up exactly what you picked.

Note that Beaver’s model is a table of IFC/STEP instances, not an AutoCAD-style model
space. To find something, ask for its IFC type. beaver_get_model_summary and
beaver_list_entity_types say which types this particular drawing actually uses, so the
AI does not have to guess.

Coordinates and quantities come back in the drawing’s own length unit, which
beaver_get_model_summary reports Eusually millimetres for files exported from Revit
or ArchiCAD.

The size reported by beaver_get_placement is measured from the polygons Beaver draws,
so it is a good approximation rather than an exact dimension. When a drawing carries
real quantities, beaver_get_quantities returns those instead.

What the AI can point at

These tools are always available too. They do not change your drawing Eonly what is on
screen, in the same way that clicking and zooming does.

Tool	What it does
`beaver_select_instances`	Select elements on screen, so the AI can show you which ones it means.
`beaver_zoom_to`	Zoom to the given elements, or to the whole drawing.
`beaver_set_view`	Turn the view: a plan from above, an elevation from any side, or an isometric view of the whole model.

Together with beaver_export_image these let the AI answer with a picture rather than a
description. It will normally turn the view, zoom to what it is talking about, and only
then take the picture.

What the AI can change

These tools appear only while MCPSERVERALLOWWRITE is ON. While it is OFF they are
neither listed nor executed. They are the ones that write to your drawing, to your
settings, or to a file on disk.

Tool	What it does
`beaver_new_document`	Start a new drawing from the IFC template.
`beaver_open_document`	Open an `.ifc` file. If it is already open, that one is activated instead of being opened twice.
`beaver_save`	Save the active drawing over the file it came from.
`beaver_save_as`	Save the active drawing to a new `.ifc` path.
`beaver_close_document`	Close a drawing. If it has unsaved changes it is not closed unless you allow the changes to be thrown away.
`beaver_add_instance`	Add a new, empty IFC entity of a given type and return its id.
`beaver_set_attribute`	Write one attribute of one entity.
`beaver_delete_instances`	Delete entities by id.
`beaver_undo`	Undo the last change, the same as Beaver’s own Undo.
`beaver_redo`	Redo what was undone.
`beaver_run_command`	Run one of Beaver’s commands, with its answers supplied up front.
`beaver_answer_prompt`	Answer a command that is waiting for input, as if you typed it in the command pane.
`beaver_cancel`	Cancel what Beaver is waiting for, the same as pressing Esc.
`beaver_set_sysval`	Change a system variable.
`beaver_export_image`	Save a picture of the 3D view to a file and return the path.
`beaver_export_model`	Write the geometry to an STL, OBJ or FBX file, or a grid view to CSV.

beaver_export_image copies the Beaver window, so Beaver is brought to the front to
take the picture. If the window is minimised or covered, the picture may not be right.

The AI cannot make Beaver forget your work by accident: beaver_close_document refuses
to close a drawing with unsaved changes unless it is told explicitly to discard them,
and system variables report the value they had before the change so the AI can put them
back. The two export tools only ever write to the path you asked for, and refuse a path
whose extension does not match what they produce.

beaver_cancel is what gets the AI out of a stuck command. If a command needs a value
that the AI did not supply, Beaver stops and waits for it; cancelling takes the command
back rather than leaving Beaver waiting for you.

beaver_add_instance, beaver_set_attribute and beaver_delete_instances edit the IFC
instance table directly, which is how the AI can build something Beaver has no command
for Ea profile to give the Wall or Column command, for example. They work at a lower
level than Beaver’s own commands: a new entity starts out empty and nothing is done on
its behalf, so it is up to the AI to fill in what the schema requires. Each call is one
transaction, so beaver_undo takes back a whole call, and a call that fails part way
leaves the drawing as it was. Deleting removes exactly the entities named and does not
tidy up references to them, unlike the Delete command, which works on whole elements.

While Beaver is busy

Beaver runs one command at a time. If a command is waiting for you to pick a point or a
dialog is open, a new command cannot start. In that case the tools report that Beaver is
waiting for input instead of hanging, and beaver_status tells the AI what it is waiting
for. Finish or cancel what is on screen and the AI can continue.

If Beaver stays busy longer than MCPSERVERTIMEOUT, the request fails with a timeout
rather than waiting forever.

Security

The server listens on 127.0.0.1 only. It is not reachable from the network.
Requests carrying a browser Origin header from anywhere other than localhost are
rejected, so a web page you happen to have open cannot drive Beaver.
Tools that change state stay hidden until you set MCPSERVERALLOWWRITE to ON.
There is no password. Any program running as you on this machine can reach the server
while it is on, so leave MCPSERVER off when you do not need it.

Stopping the server

_CliCmdMcpServer with the stop argument stops it, and status reports the current
state. The command pane passes the whole line as a command name, so those arguments can
only be given from the COM or .NET API, using the "name\nargument\n" form of
SendStringToExecute. Quitting Beaver also stops the server.