Tekla MCP Server

This server facilitates interaction with Tekla Structures, helping users speed up modeling processes. It acts as a bridge between users and Tekla, enabling automated workflows and improving efficiency.

📌 What is MCP?

MCP stands for Model Context Protocol, a communication protocol introduced by Anthropic to enable more efficient and secure interactions between large language models and other systems.

Tekla MCP Server uses AI-powered natural language processing to make interactions more human-readable, allowing you to work with Tekla Structures using plain text commands.

🚀 Features

Tools Available

Tool	Description
put_components	Insert Tekla components into selected elements with custom properties
remove_components	Remove Tekla components from selected elements
select_elements_by_filter	Select elements by type, name, profile, material, finish, phase
select_elements_by_filter_name	Select elements using predefined filter names
select_elements_by_guid	Select elements by their GUID
select_elements_assemblies_or_main_parts	Get assemblies or main parts of selected elements
draw_elements_labels	Draw temporary labels showing element properties
zoom_to_selection	Zoom view to fit selected elements
show_only_selected	Show only selected elements in active view
cut_elements_with_zero_class_parts	Perform boolean cuts using class 0 elements
convert_cut_parts_to_real_parts	Convert cut geometry to real model parts
set_elements_udas	Set custom attributes on selected elements
get_all_elements_udas	Retrieve all custom attributes from elements
get_elements_properties	Get detailed element properties including weight and custom fields

📋 Requirements

• Tekla Structures 2023 (or compatible version)
• Python 3.11 or newer
• Required Python packages (see requirements.txt)

🔧 Installation

1. Install Dependencies

# Using uv (recommended)
uv pip install -r requirements.txt

# Using pip
pip install -r requirements.txt

⚠️ Note: You may experience a naming conflict with the clr string styling package. If this happens, rename or delete the folder:

C:\Users\<User>\AppData\Local\Programs\Python\Python311\Lib\site-packages\clr

2. Configure Settings

The configuration files are already set up for Tekla 2023. If you need to adjust paths:

1. Edit config/settings.json:

{
  "tekla_path": "C:\\Program Files\\Tekla Structures\\2023.0\\bin",
  "content_attributes_file_path": "C:\\Program Files\\Tekla Structures\\2023.0\\bin\\applications\\Tekla\\Tools\\TplEd\\settings\\contentattributes_global.lst"
}

2. Customize config/element_types.json for your Tekla classes
3. Customize config/base_components.json with your component catalog numbers
4. Customize config/lifting_anchor_types.json for lifting anchor components

3. Set Up MCP Client

Configure mcp_server.py as a custom MCP server in your MCP client:

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "tekla": {
      "command": "python",
      "args": ["d:\\VS\\TeklaMCPServer\\mcp_server.py"]
    }
  }
}

For other MCP clients: Consult your client's documentation for custom server configuration.

🧪 Testing

The project includes comprehensive unit and functional tests:

# Run all unit tests
uv run pytest tests/unit/

# Run all tests (functional tests skip if Tekla not running)
uv run pytest tests/

# Run specific test file
uv run pytest tests/unit/test_models.py

# Run functional tests (requires Tekla running)
uv run pytest tests/functional/ --run-functional

⚠️ Warning: Functional tests modify the actual Tekla model. Run them only in test/development environment.

📦 Distribution

Create a standalone executable using PyInstaller:

# Install PyInstaller
uv pip install pyinstaller

# Build executable
uv run pyinstaller mcp_server.py

The executable will be in dist/mcp_server/. Include the _internals directory when distributing.

Note: When using the executable, copy configuration files to _internals/config/.

💡 Usage Examples

With Natural Language (via MCP Client)

"Select all beams with IPE300 profile and add lifting anchors"
"Get properties of selected columns"
"Show only elements in phase 1"
"Zoom to selected elements"

Direct Tool Usage

The server exposes MCP tools that can be called programmatically:

# Example: Select elements by filter
{
  "tool": "select_elements_by_filter",
  "arguments": {
    "element_type": "beam",
    "profile": "IPE300",
    "material": "S355"
  }
}

🔍 How It Works

Architecture

┌─────────────────┐
│   MCP Client    │  (Claude Desktop, DeepChat, etc.)
│   (AI Model)    │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  mcp_server.py  │  ← Main server implementation
└────────┬────────┘
         │
         ├─→ models.py         (Data structures)
         ├─→ tekla_utils.py    (Tekla API wrapper)
         └─→ config/*.json     (Configuration)
                │
                ▼
         ┌──────────────┐
         │    Tekla     │  (via .NET API)
         │  Structures  │
         └──────────────┘

Key Components

1. MCP Server (mcp_server.py): Handles MCP protocol communication and routes tool calls
2. Tekla Utilities (tekla_utils.py): Wraps Tekla .NET API for Python access via pythonnet
3. Data Models (models.py): Pydantic models for type-safe data handling
4. Configuration: JSON files for customizing behavior per project

MCP Protocol Integration

The server uses the mcp Python package to:

• Register available tools via @app.list_tools()
• Handle tool execution requests via @app.call_tool()
• Communicate over stdio with MCP clients
• Provide structured responses using Pydantic models

Tekla API Usage

Tekla integration uses pythonnet (CLR) to:

• Load Tekla .NET assemblies dynamically
• Access Tekla.Structures.Model namespace
• Perform modeling operations (select, modify, insert components)
• Query element properties and user-defined attributes

✅ Verified Compatibility

Tekla Version: 2023

MCP Clients:

• DeepChat
• chatmcp

AI Models:

• GPT-4o
• DeepSeek
• Gemini 2.0 Flash
• Qwen3

📝 License

This software is open-source and released under the GPLv3 license. You are free to use, modify, and distribute it, as long as all modifications remain open-source under the same license.

See LICENSE for full details.

⚠️ Disclaimer

This software is provided as is, without any warranties or guarantees of functionality, reliability, or security. The developer assumes no responsibility for any damages, data loss, or other issues arising from its use.

Use at your own risk.

🤝 Contributing

Contributions are welcome! Please ensure:

• All tests pass before submitting PR
• New features include appropriate tests
• Code follows existing style conventions
• Configuration remains backward compatible

📞 Support

For issues and questions:

• Check existing GitHub issues
• Review test files for usage examples
• Consult Tekla API documentation for advanced usage

🗺️ Roadmap

Future enhancements (contributions welcome):

• Support for Tekla 2024+
• Additional intelligent components
• Enhanced filtering capabilities
• Drawing automation tools
• Report generation features