Archicad Tapir MCP Server

This project provides a Model Context Protocol (MCP) server for Archicad. It acts as a bridge, allowing AI agents and applications (like Claude for Desktop) to interact with running Archicad instances by wrapping both the community-driven Tapir API and the official Archicad JSON API.

The server dynamically generates a comprehensive set of 137 MCP tools from the combined API schemas, enabling fine-grained control over Archicad projects.

Disclaimer: This project is in an early stage of development. It has not been extensively tested and is intended primarily for experimental and educational purposes. Interfaces and functionality may change in future updates. Please use with caution.

Key Features

• Intelligent Tool Discovery: The server exposes a simple discover_tools function that uses a powerful local semantic search engine to find the most relevant Archicad command from a user's natural language query.
• Massive Toolset, Minimal Footprint: Provides access to a unified toolset of 137 commands (and growing) by intelligently merging the community Tapir API and the official Archicad JSON API, without overwhelming the AI's context window.
• 100% Local & Private Search: The semantic search index is built and runs entirely on your machine using sentence-transformers and faiss-cpu. No data ever leaves your computer, and no API keys are required.
• Adaptive & Relevant Results: Search uses a sophisticated "Top-Score Relative Threshold" to filter out noise and return only the most relevant tools for a given query.
• Multi-Instance Control: Connect to and manage multiple running Archicad instances simultaneously.
• Robust & Packaged: Designed as a proper Python package with a pyproject.toml, enabling simple and reliable installation.

Installation & Setup

Follow these steps to get the server running and connected to an MCP client like Claude for Desktop.

1. Prerequisites

• Python 3.12+ and uv: Ensure you have a modern version of Python and the uv package manager installed. You can install uv with pip install uv.
• Archicad & Tapir Add-On: You must have Archicad running (which includes the official JSON API). To access the full set of community-developed tools, the Tapir Archicad Add-On must also be installed.
• MCP Client: An application that can host MCP servers, such as Claude for Desktop or Gemini CLI

2. Configure Your AI Client

This is now the only step required. Open your client's config.json file and add the following configuration. This command is universal and works on any operating system without modification.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ArchicadTapir": {
      "command": "uvx",
        "args": [
          "--from",
          "tapir-archicad-mcp",
          "archicad-server"
        ]
    }
  }
}

How This Works: The uvx command (part of the uv toolchain) is a powerful utility that automatically handles the entire process for you:

1. The first time the AI client needs the tool, uvx will download the latest version of tapir-archicad-mcp from PyPI.
2. It will install it into a temporary, isolated environment.
3. It will run the server.

Usage

1. Restart Claude for Desktop to apply the configuration changes.
2. Ensure at least one instance of Archicad (with Tapir) is running.
3. The client will now have access to a small set of core

... View full README on GitHub