Revit MCP Python

MCP server for Revit - Python

Uma implementação orientada a pyRevit do Model Context Protocol (MCP) para Autodesk Revit

Como?

• Esta implementação mínima utiliza o módulo Routes dentro do pyRevit para criar uma ponte entre o Revit e Grandes Modelos de Linguagem (LLMs).
• Ela fornece um modelo simples para começar rapidamente, permitindo prototipar e iterar ferramentas para dar aos LLMs acesso aos seus modelos Revit.
• Estas ferramentas são projetadas para serem expandidas para seus casos de uso específicos. Você é muito bem-vindo a fazer um fork do repositório e fazer suas próprias contribuições.
• Nota: A API Routes do pyRevit está atualmente em formato de rascunho e sujeita a alterações. Ela não possui mecanismos de autenticação integrados, então você precisará implementar suas próprias medidas de segurança para uso em produção.

Baterias Incluídas

Este repositório é destinado a:

• Iniciantes na API do Revit
• Especialistas em Python que não são versados em C#
• Qualquer pessoa que queira prototipar e iterar rapidamente com LLMs e Revit

Ele contém:

• Uma implementação completa de Routes para pyRevit
• Um script mínimo de servidor MCP para conectar a qualquer cliente compatível com MCP
• Vários comandos de teste para começar imediatamente

Principais Componentes de Arquitetura

O sistema roda como dois servidores separados trabalhando juntos em cadeia:

Claude / LLM Client
       |
       |  MCP Protocol (stdio or HTTP)
       v
  main.py  (MCP Server)
       |
       |  HTTP requests (localhost:48884)
       v
  pyRevit Routes  (REST API running inside Revit)
       |
       |  Revit API calls
       v
  Revit Application

main.py é o servidor MCP. Ele fala o protocolo MCP para que Claude (ou qualquer cliente compatível com MCP) possa chamar ferramentas. Quando uma ferramenta é chamada, main.py a traduz em uma solicitação HTTP e a encaminha ao Revit.

pyRevit Routes é uma API REST leve que roda dentro do processo do Revit. Ela recebe essas solicitações HTTP, executa o código da API do Revit (já que possui acesso direto à instância em execução) e retorna respostas em JSON.

Eles nunca entram em conflito porque desempenham papéis diferentes, falam protocolos diferentes e escutam em portas diferentes.

Nota: As ferramentas Launch & Document (launch_revit, list_revit_installations) são a exceção — elas rodam inteiramente no lado do MCP, usando subprocess para iniciar o Revit e então fazendo polling do endpoint de saúde do pyRevit Routes até que a ponte esteja pronta.

1. Servidor MCP (main.py):

• Construído com FastMCP
• Lida com comunicação HTTP com a API Revit Routes
• Registra ferramentas a partir do sistema modular de ferramentas
• Fornece funções auxiliares para solicitações GET/POST/Imagem

2. Extensão pyRevit (revit-mcp-python.extension/):

• Contém a API Routes que roda dentro do Revit
• Registro modular de rotas em startup.py
• Módulos de rota individuais no diretório revit_mcp/

3. Sistema de Registro de Ferramentas (tools/):

• Organização modular de ferramentas por funcionalidade
• Registro central através de tools/__init__.py
• Cada módulo registra suas próprias ferramentas com o servidor MCP

---

Ferramentas Suportadas

Status Atual de Implementação

Nome da Ferramenta	Status	Categoria	Descrição
get_revit_status	✅ Implementado	Status e Conectividade	Verifica se a API Revit-MCP está ativa e respondendo
get_revit_model_info	✅ Implementado	Informações do Modelo	Obtém informações abrangentes sobre o modelo Revit atual
list_levels	✅ Implementado	Informações do Modelo	Obtém todos os níveis com informações de elevação
get_revit_view	✅ Implementado	Vista e Imagem	Exporta uma vista específica do Revit como imagem
list_revit_views	✅ Implementado	Vista e Imagem	Obtém uma lista de todas as vistas exportáveis organizadas por tipo
place_family	✅ Implementado	Família e Posicionamento	Posiciona uma instância de família em local especificado com propriedades personalizadas
list_families	✅ Implementado	Família e Posicionamento	Obtém uma lista plana de tipos de família disponíveis (com filtragem)
list_family_categories	✅ Implementado	Família e Posicionamento	Obtém uma lista de todas as categorias de família no modelo
get_current_view_info	✅ Implementado	Informações da Vista	Obtém informações detalhadas sobre a vista atualmente ativa
get_current_view_elements	✅ Implementado	Informações da Vista	Obtém todos os elementos visíveis na vista atual
create_point_based_element	✅ Implementado	Criação de Elementos	Cria elementos baseados em pontos (portas, janelas, mobiliário)
color_splash	✅ Implementado	Visualização	Colore elementos com base em valores de parâmetros
execute_revit_code	✅ Implementado	Execução de Código	Executa código IronPython diretamente no contexto do Revit
list_revit_installations	✅ Implementado	Launch & Document	Descobre todas as versões do Revit instaladas no sistema
launch_revit	✅ Implementado	Launch & Document	Inicia o Revit, opcionalmente com um arquivo, e verifica a prontidão
open_document	✅ Implementado	Launch & Document	Abre um documento no Revit em execução (suporta desanexar e auditoria)
close_document	✅ Implementado	Launch & Document	Fecha o documento ativo
save_document	✅ Implementado	Launch & Document	Salva ou Salva Como o documento ativo
sync_with_central	✅ Implementado	Launch & Document	Sincroniza um documento de trabalho compartilhado com o central
get_selected_elements	🔄 Pendente	Gerenciamento de Seleção	Obtém informações sobre os elementos atualmente selecionados
create_line_based_element	🔄 Pendente	Criação de Elementos	Cria elementos baseados em linhas (paredes, vigas, tubulações)
create_surface_based_element	🔄 Pendente	Criação de Elementos	Cria elementos baseados em superfícies (pisos, lajes, tetos)
delete_elements	🔄 Pendente	Gerenciamento de Elementos	Exclui elementos especificados do modelo
modify_element	🔄 Pendente	Gerenciamento de Elementos	Modifica propriedades de elementos (parâmetros de instância)
reset_model	🔄 Pendente	Gerenciamento de Elementos	Redefine o modelo excluindo elementos do modelo de processo
tag_walls	🔄 Pendente	Anotação	Etiqueta todas as paredes na vista atual
search_modules	🔄 Pendente	Integração	Pesquisa por módulos/addins disponíveis
use_module	🔄 Pendente	Integração	Executa funcionalidades de módulos externos

Começando

Instalando o uv:

Consulte ./README_UV.md

Instalando a Extensão no Revit

Ativar pyRevit Routes

1. No Revit, navegue até a aba pyRevit
2. Abra Configurações
3. Vá para Routes > ative Routes Server O pyRevit começará a escutar na porta http://localhost:48884/

Instalar a partir do pyRevit:

1. No Revit, navegue até a aba pyRevit
2. Abra Extensões
3. Selecione a Extensão MCP Server for Revit Python > Instalar extensão
4. Selecione o local, o padrão é %APPDATA%\Roaming\pyRevit\Extensions
5. Ative e aguarde o pyRevit recarregar. Reinicie o Revit se necessário.

Instalação Manual em um diretório personalizado:

1. Clone o repositório em um local personalizado:

   git clone https://github.com/mcp-servers-for-revit/mcp-server-for-revit-python
   

2. Adicione .extension ao nome da pasta raiz
3. No Revit, navegue até a aba pyRevit
4. Abra Configurações
5. Em "Extensões Personalizadas", adicione o caminho para a pasta .extension
6. Salve as configurações e recarregue o pyRevit (talvez seja necessário reiniciar o Revit completamente)

Testando Sua Conexão

Após a instalação, teste se a API Routes está funcionando:

1. Abra seu navegador da web e acesse:

   http://localhost:48884/revit_mcp/status/
   

2. Se for bem-sucedido, você deverá ver uma resposta como:

   {"status": "active",
    "health": "healthy",
    "revit_available": true,
    "document_title": "your_revit_filename",
    "api_name": "revit_mcp"}
   

O Serviço Routes será carregado automaticamente sempre que você iniciar o Revit. Para desativá-lo, basta remover o caminho da extensão nas configurações do pyRevit.

Usando o Cliente MCP

Testando com o MCP Inspector

O SDK MCP inclui uma ferramenta de inspeção útil para depuração:

mcp dev main.py

Em seguida, acesse http://127.0.0.1:6274 no seu navegador para testar seu servidor MCP interativamente.

Modos de Transporte

O servidor MCP suporta vários modos de transporte para diferentes casos de uso:

Flag	Transporte	Endpoints	Caso de Uso
(nenhum)	stdio	stdin/stdout	Claude Desktop / Claude Code padrão
--sse	Somente SSE	/sse, /messages/	Clientes legados
--streamable-http	Somente HTTP	/mcp	Clientes HTTP modernos
--combined	Ambos	Todos acima	Compatibilidade máxima

Executando com transporte combinado (recomendado para HTTP):

uv run --with "mcp[cli]" main.py --combined

Isso inicia o servidor em http://127.0.0.1:8000 com ambos os endpoints SSE e HTTP streamable disponíveis.

Testando os endpoints:

# Test streamable-http
curl -X POST http://localhost:8000/mcp

# Test SSE
curl http://localhost:8000/sse

Conectando ao Claude Desktop

A maneira mais simples de instalar seu servidor MCP no Claude Desktop:

mcp install main.py

Ou para instalação manual:

1. Abra Claude Desktop → Configurações → Desenvolvedor → Editar Config
2. Adicione isto à seção mcpServers:

{
  "mcpServers": {
    "Revit Connector": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/absolute/path/to/main.py"
      ]
    }
  }
}

Para o modo de transporte HTTP, configure o Claude Desktop com:

{
  "mcpServers": {
    "Revit Connector": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Conectando ao Claude Code

claude mcp add -s user "Revit-Connector" -- uv run --with "mcp[cli]" mcp run /absolute/path/to/main.py

Criando Suas Próprias Ferramentas

A arquitetura modular deste projeto torna a adição de funcionalidades relativamente simples. O arquivo LLM.txt fornecido também dá ao seu modelo de linguagem o contexto necessário para começar imediatamente.

O processo envolve três partes principais:

Parte 1: Criar o Módulo de Rota no Revit

Crie um novo arquivo Python dentro do diretório revit-mcp-python.extension/revit_mcp/ (por exemplo, revit_mcp/your_module.py). Este módulo conterá todas as funções relacionadas que você deseja expor.

# In revit-mcp-python.extension/revit_mcp/your_module.py

# -*- coding: UTF-8 -*-
"""
Your Module for Revit MCP
Handles your specific functionality.
"""
from pyrevit import routes, revit, DB
import json
import logging

# Standard logger setup
logger = logging.getLogger(__name__)

def register_your_routes(api):
    """Register all your routes with the API."""

    # ---- Example 1: A GET request for reading data ----
    @api.route('/your_endpoint/', methods=["GET"])
    def get_project_title(doc):
        """Gets the project title from the Revit model."""
        try:
            value = doc.Title
            return routes.make_response(data={"status": "success", "data": value})
        except Exception as e:
            logger.error("Get project title failed: {}".format(str(e)))
            return routes.make_response(data={"error": str(e)}, status=500)

    # ---- Example 2: A POST request for modifying the model ----
    @api.route('/modify_model/', methods=["POST"])
    def modify_model(doc, request):
        """Handles POST requests for modifying the Revit model."""
        try:
            data = json.loads(request.data) if isinstance(request.data, str) else request.data

            # Use a transaction for all model modifications
            t = DB.Transaction(doc, "Modify Model via MCP")
            t.Start()

            try:
                element_id = data.get("element_id")
                new_value = data.get("new_value")
                element = doc.GetElement(DB.ElementId(int(element_id)))
                param = element.LookupParameter("Comments")
                param.Set(new_value)

                t.Commit()
                return routes.make_response(data={"status": "success", "result": "Element modified."})

            except Exception as tx_error:
                if t.HasStarted() and not t.HasEnded():
                    t.RollBack()
                raise tx_error

        except Exception as e:
            logger.error("Modify model failed: {}".format(str(e)))
            return routes.make_response(data={"error": str(e)}, status=500)

    logger.info("Your custom routes were registered successfully.")

Parte 2: Criar o Módulo de Ferramenta MCP

Crie as ferramentas correspondentes para o servidor MCP no diretório tools/ (por exemplo, tools/your_tools.py). Este módulo usará os auxiliares revit_get e revit_post de main.py.

# In tools/your_tools.py
# -*- coding: utf-8 -*-
"""Your tools for the MCP server."""

from mcp.server.fastmcp import Context
from .utils import format_response

def register_your_tools(mcp, revit_get, revit_post, revit_image=None):
    """Register your tools with the MCP server."""

    # ---- Tool for the GET request ----
    @mcp.tool()
    async def get_revit_project_title(ctx: Context) -> str:
        """
        Retrieves the title of the currently open Revit project.
        """
        response = await revit_get("/your_endpoint/", ctx)
        return format_response(response)

    # ---- Tool for the POST request ----
    @mcp.tool()
    async def modify_revit_element_comment(
        element_id: int,
        new_value: str,
        ctx: Context = None
    ) -> str:
        """
        Modifies the 'Comments' parameter of a specific element.

        Args:
            element_id: The ID of the element to modify.
            new_value: The new comment to apply to the element.
        """
        payload = {"element_id": element_id, "new_value": new_value}
        response = await revit_post("/modify_model/", payload, ctx)
        return format_response(response)

Parte 3: Registrar Seus Novos Módulos

1. Registrar o Módulo de Rota

Abra revit-mcp-python.extension/startup.py e adicione sua nova função de registro de rota.

# In revit-mcp-python.extension/startup.py

# ... (other imports)
# Import the registration function from your new module
from revit_mcp.your_module import register_your_routes

def register_routes():
    """Register all MCP route modules"""
    api = routes.API('revit_mcp')
    try:
        # ... (existing route registrations)

        # Register your new routes (this registers all functions inside)
        register_your_routes(api)

        logger.info("All MCP routes registered successfully")
    except Exception as e:
        logger.error("Failed to register MCP routes: {}".format(str(e)))
        raise

2. Registrar o Módulo de Ferramenta

Abra tools/__init__.py e adicione sua nova função de registro de ferramenta.

# In tools/__init__.py

# ... (other tool imports)
# Import the registration function from your new tool module
from .your_tools import register_your_tools

def register_tools(mcp_server, revit_get_func, revit_post_func, revit_image_func):
    """Register all tools with the MCP server"""

    # ... (existing tool registrations)
    # Register your new tools (this registers all tools inside)
    register_your_tools(mcp_server, revit_get_func, revit_post_func, revit_image_func)

    return mcp_server

Roadmap

Este é um trabalho em andamento e mais uma demonstração do que um produto completo. Melhorias futuras poderiam incluir:

• Criando um Cliente dentro do Revit
• Implementando compatibilidades com outros modelos de linguagem
• Autenticação e melhorias de segurança
• Ferramentas e capacidades mais avançadas do Revit
• Melhor tratamento de erros e recursos de depuração
• Benchmarking com modelos locais
• Documentação e exemplos para casos de uso comuns
• ...

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar pull requests ou abrir issues para quaisquer bugs ou solicitações de recursos. Sinta-se à vontade para entrar em contato comigo se tiver dúvidas ou ideias.