# Sample MCP Server for Revit Automation

[![Automation API](https://img.shields.io/badge/Automation-v3-green.svg)](http://developer.autodesk.com/)
[![Revit-2026](https://img.shields.io/badge/Revit%20API-2026-lightgrey.svg)](http://autodesk.com/revit)
[![.NET](https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet)](https://dotnet.microsoft.com/)
[![C#](https://img.shields.io/badge/C%23-14.0-239120?logo=csharp)](https://docs.microsoft.com/en-us/dotnet/csharp/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io)

A sample Model Context Protocol (MCP) remote server (HTTP) that enables AI assistants like Claude to automate Autodesk Revit operations via [Automation API](https://aps.autodesk.com/developer/overview/automation-api) using [Service-to-Service Authentication (SSA)](https://aps.autodesk.com/en/docs/ssa/v1/developers_guide/overview/).

https://github.com/user-attachments/assets/43a5aabc-d2a3-47ff-a9e1-8bd61d24a81e

---

> **⚠️ Disclaimer**  
> This is a **vibe-coded sample solution** - an exploratory proof-of-concept developed iteratively. It demonstrates patterns and possibilities but may not follow all production-grade practices. This README was generated by **GitHub Copilot** based on analyzing the actual codebase, ensuring documentation matches implementation.

> **🔗 Companion Repository**  
> This MCP server works with the [APS Automation API Revit MCP Tools Sample](https://github.com/autodesk-platform-services/aps-automation-api-revit-mcp-tools-sample) - the Revit AppBundle that executes the actual tools in Automation API. Deploy that AppBundle to use this MCP server.

---

## 🎯 Overview

**MCP Revit Automation** bridges AI assistants with Autodesk Revit through the Model Context Protocol. It enables headless, scalable automation of Revit operations on cloud-hosted models (ACC/BIM360) without manual interaction.

**Target Audience:** AEC Firms, BIM Managers, BIM Coordinators, Developers building AI-powered BIM workflows

### Key Features

- 🔐 **SSA Authentication** - JWT bearer tokens with RSA signing for service-to-service auth
- 🏗️ **Fluent API** - Type-safe model configuration with compile-time validation
- 📦 **Dual JSON Architecture** - Separates model context from tool inputs
- 🤖 **MCP Integration** - Exposes tools to AI assistants naturally
- ☁️ **Cloud-Native** - Works with Autodesk Cloud Models

### 🔧 Extensible Tool System
- Easy to add new Revit automation tools
- Consistent pattern for all operations
- No core service changes required

### 🤖 MCP Protocol Support
- Exposes tools to AI assistants like Claude or VS Code Copilot
- Natural language to Revit automation
- HTTP transport for broad compatibility

### ☁️ Cloud-Native
- Works with Autodesk Cloud Models (ACC/BIM360) - Workshared and Non-Workshared
- Scalable workitem submission
- Automation API for Revit integration

---

## 🏛️ Architecture

```
MCP Client (Claude/VS Code) 
    ↓ MCP Protocol
MCP Server (This Project)
    ├─ RevitAutomationTools (MCP tool definitions)
    ├─ RevitAutomationService (Workitem submission)
    └─ SsaTokenService
    ↓ HTTPS + Bearer Token
Autodesk Automation API for Revit (Cloud execution)
```

**Dual JSON Pattern:**  
- `revitmodel.json` - Model context (region, project, model GUIDs, tool name)  
- `toolinputs.json` - Tool-specific parameters

---

## 📦 Prerequisites

- **.NET 10 SDK** ([Download](https://dotnet.microsoft.com/download))
- An **Autodesk Platform Services** Sever-to-Server App with Automation API enabled
- **Service Account** configured ([SSA Management Tool](https://aps.autodesk.com/en/docs/ssa/v1/code_samples_blog_post/code_samples/))
- **Automation Activity** deployed for [APS Automation API Revit MCP Tools Sample](https://github.com/autodesk-platform-services/aps-automation-api-revit-mcp-tools-sample)

---

## 🚀 Installation

```bash
git clone https://github.com/autodesk-platform-services/aps-sample-mcp-server-revit-automation.git
cd mcp-revit-automation
dotnet restore
dotnet build --configuration Release
```

Create `appsettings.json`:

```json
{
  "Forge": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "ServiceAccountId": "your-service-account-id",
    "KeyId": "your-key-id",
    "PrivateKeyPath": "path/to/private-key.pem"
  }
}
```

Run (http): `dotnet run`

---

## ⚙️ Configuration

**Obtain credentials from [APS Developer Portal](https://aps.autodesk.com/):**

1. Create APS application with Automation API enabled → Get `ClientId` & `ClientSecret`
2. Create Service Account → Generate RSA key pair → Get `ServiceAccountId` & `KeyId`
3. Download private key as `.pem` file → Set path in `PrivateKeyPath`

---

## 📘 Usage

### MCP Client Configuration

**Visual Studio Code:**
See how to configure an MCP Server [here](https://learn.microsoft.com/en-us/dotnet/ai/quickstarts/build-mcp-server?pivots=visualstudio#configure-the-mcp-server)
```json
{
 "inputs": [],
  "servers": {
    "revit-automation-mcp": {
      "url": "http://localhost:6223",
      "type": "http"
    }
  }
}
```

### Fluent API Example

```csharp
// Model configuration (type-safe, compile-time validated)
var modelConfig = ModelConfiguration.Create()
    .WithRegion("US")
    .WithProject("project-guid")
    .WithModelGuid("model-guid")
    .WithToolName("link_models")
    .Save(true)
    .Configure();

// Tool-specific inputs (flexible dictionary)
var toolInputs = new Dictionary<string, object>
{
    { "modelName", "My Model" },
    { "linksToAdd", new[] { new { modelName = "Link1", modelGuid = "guid1" } } },
    { "linksToRemove", Array.Empty<object>() }
};

var result = await service.SubmitWorkItemAsync(modelConfig, toolInputs);
```
---

## 🛠️ Available Tools

| Tool | Description |
|------|-------------|
| `create_model` | Creates a new Revit model from template |
| `link_models` | Adds/removes Revit model links |

#### Creating a Revit Model
**revitmodel.json**
```json
{
  "region": "US",
  "projectGuid": "00000000-0000-0000-0000-000000000000",
  "modelGuid": "11111111-1111-1111-1111-111111111111",
  "toolName": "create_model",
  "save": false
}
```
**toolinputs.json**
```json
{
  "enableWorksharing": true,
  "accountId": "00000000-0000-0000-0000-000000000000",
  "projectId": "00000000-0000-0000-0000-000000000000",
  "folderId": "urn:adsk.wipprod:fs.folder:co.example",
  "modelName": "NewModel.rvt"
}
```

#### Managing Model Links
**revitmodel.json**
```json
{
  "region": "US",
  "projectGuid": "00000000-0000-0000-0000-000000000000",
  "modelGuid": "00000000-0000-0000-0000-000000000000",
  "toolName": "link_models",
  "save": true
}
```
**toolinputs.json**
```json
{
  "region": "US",
  "projectGuid": "00000000-0000-0000-0000-000000000000",
  "linksToAdd": [
    {
      "modelName": "Architectural_Link.rvt",
      "modelGuid": "11111111-1111-1111-1111-111111111111"
    },
    {
      "modelName": "Structural_Link.rvt",
      "modelGuid": "22222222-2222-2222-2222-222222222222"
    }
  ],
  "linksToRemove": [
    {
      "modelName": "Old_Link.rvt",
      "modelGuid": "99999999-9999-9999-9999-999999999999"
    }
  ]
}
```

## ➕ Adding New Tools

**1. In Tools/RevitAutomationTools.cs**
```csharp
[McpServerTool(Name = "my_tool")]
public async Task<WorkItemSubmissionResult> MyTool(...)
{
    var modelConfig = ModelConfiguration.Create()
        .WithRegion(region)
        .WithProject(projectGuid)
        .WithModelGuid(modelGuid)
        .WithToolName("my_tool")
        .Configure();
    
    var toolInputs = new Dictionary<string, object> { /* tool params */ };
    return await revitAutomationService.SubmitWorkItemAsync(modelConfig, toolInputs);
}

```
**2. In your Revit AppBundle: add case for "my_tool"**. See how to add new tools [here](https://github.com/autodesk-platform-services/aps-automation-api-revit-mcp-tools-sample?tab=readme-ov-file#creating-custom-tools)

---

## Resources

- **Revit AppBundle (Companion Repo)**: [aps-automation-api-revit-mcp-tools-sample](https://github.com/autodesk-platform-services/aps-automation-api-revit-mcp-tools-sample)
- **APS Portal**: [aps.autodesk.com](https://aps.autodesk.com/)
- **APS Automation API**: [Documentation](https://aps.autodesk.com/developer/overview/automation-api)
- **APS SSA API**: [Developer Guide](https://aps.autodesk.com/en/docs/ssa/v1/developers_guide/overview/)
- **MCP Spec**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **.NET MCP Server Template**: [microsoft learn](https://learn.microsoft.com/en-us/dotnet/ai/quickstarts/build-mcp-server?pivots=visualstudio#configure-the-mcp-server)

---
## License

This sample is licensed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
Please see the [LICENSE](LICENSE) file for full details.

---

**Made with ❤️ for the AEC community | Vibe-coded with GitHub Copilot**