AI导哈

商业注册查询服务

提供德国商业注册数据访问服务，支持企业搜索、注册信息提取、公司数据和年度财务报表查询。

  • by EliaLesyk
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 EliaLesyk/mcp-handelsregister

使用说明

Handelsregister MCP-Server

MCP-Server fuer den Zugriff auf das deutsche Handelsregister. Ermoeglicht KI-Assistenten die Suche nach Unternehmen, den Abruf von Handelsregisterauszuegen, Firmendaten und Jahresabschluessen.

Funktioniert sofort ohne API-Key - die kostenlose handelsregister.de-Quelle ist Standard.

Fuer wen?

  • Steuerberater - Mandantenrecherche, Gesellschafterstrukturen, Jahresabschluesse
  • Rechtsanwaelte - Due Diligence, Vertretungsbefugnisse, Gesellschaftsrecht
  • Wirtschaftspruefer - Unternehmensanalyse, Beteiligungsstrukturen, Bilanzanalyse

Funktionen

Tool Beschreibung
search_company Unternehmenssuche nach Name, Ort, Rechtsform oder Registernummer
get_company_details Vollstaendige Firmendaten: Rechtsform, Sitz, Gegenstand, Kapital, Geschaeftsfuehrer
get_handelsregister_auszug Aktueller (AD) und chronologischer (CD) Handelsregisterauszug
get_company_officers Geschaeftsfuehrer, Prokuristen, Gesellschafter (aktuell + historisch)
get_jahresabschluss Jahresabschluesse (Bilanz und GuV) aus dem Bundesanzeiger via OpenRegister.de

Schnellstart

Voraussetzung

uv muss installiert sein:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

1. Repo klonen

git clone https://github.com/EliaLesyk/mcp-handelsregister.git
cd mcp-handelsregister
uv sync

2. MCP-Client konfigurieren

Waehle deinen Client:

Claude Desktop (macOS)

Oeffne ~/Library/Application Support/Claude/claude_desktop_config.json und fuege hinzu:

{
  "mcpServers": {
    "handelsregister": {
      "command": "uv",
      "args": [
        "--directory", "/DEIN/PFAD/ZU/mcp-handelsregister",
        "run", "python", "-m", "mcp_handelsregister.server"
      ]
    }
  }
}

Wichtig: Ersetze /DEIN/PFAD/ZU/mcp-handelsregister mit dem tatsaechlichen Pfad. Falls uv nicht gefunden wird, nutze den vollen Pfad (z.B. /Users/name/.local/bin/uv). Den Pfad findest du mit which uv im Terminal.

Claude Desktop (Windows)

Oeffne %APPDATA%\Claude\claude_desktop_config.json und fuege hinzu:

{
  "mcpServers": {
    "handelsregister": {
      "command": "uv",
      "args": [
        "--directory", "C:\\Dein\\Pfad\\zu\\mcp-handelsregister",
        "run", "python", "-m", "mcp_handelsregister.server"
      ]
    }
  }
}
Claude Code (CLI) 
claude mcp add handelsregister -- uv --directory /DEIN/PFAD/ZU/mcp-handelsregister run python -m mcp_handelsregister.server

Mit OpenRegister API-Key:

claude mcp add handelsregister \
  -e HR_OPENREGISTER_API_KEY=dein_key \
  -- uv --directory /DEIN/PFAD/ZU/mcp-handelsregister run python -m mcp_handelsregister.server
Cursor

In Cursor Settings > MCP Servers, fuege hinzu:

{
  "handelsregister": {
    "command": "uv",
    "args": [
      "--directory", "/DEIN/PFAD/ZU/mcp-handelsregister",
      "run", "python", "-m", "mcp_handelsregister.server"
    ]
  }
}
Windsurf

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "handelsregister": {
      "command": "uv",
      "args": [
        "--directory", "/DEIN/PFAD/ZU/mcp-handelsregister",
        "run", "python", "-m", "mcp_handelsregister.server"
      ]
    }
  }
}
Andere MCP-Clients (generisch)

Der Server kommuniziert ueber stdio. Starte ihn mit:

uv --directory /PFAD/ZU/mcp-handelsregister run python -m mcp_handelsregister.server

Jeder MCP-Client der stdio-Transport unterstuetzt kann diesen Befehl als Server-Kommando nutzen.

3. Starten

Starte deinen MCP-Client neu (z.B. Claude Desktop beenden und neu oeffnen). Der Server sollte automatisch verbinden.

Testen: Frage deinen KI-Assistenten z.B. "Suche nach der BMW AG im Handelsregister".

Optional: API-Keys fuer mehr Daten

Ohne API-Keys funktioniert nur die Basissuche ueber handelsregister.de. Fuer Gesellschafter, Jahresabschluesse und reichere Firmendaten brauchst du einen OpenRegister API-Key (kostenlos, 50 Calls/Monat).

OpenRegister API-Key (empfohlen, kostenlos)

  1. Registriere dich auf openregister.de (kostenloser Plan)
  2. Kopiere deinen API-Key
  3. Fuege den Key zur Konfiguration hinzu:

Claude Desktop - ergaenze "env" im Config:

{
  "mcpServers": {
    "handelsregister": {
      "command": "uv",
      "args": [
        "--directory", "/DEIN/PFAD/ZU/mcp-handelsregister",
        "run", "python", "-m", "mcp_handelsregister.server"
      ],
      "env": {
        "HR_OPENREGISTER_API_KEY": "dein_openregister_key"
      }
    }
  }
}

Claude Code - mit -e Flag:

claude mcp add handelsregister \
  -e HR_OPENREGISTER_API_KEY=dein_key \
  -- uv --directory /PFAD/ZU/mcp-handelsregister run python -m mcp_handelsregister.server

Alle Umgebungsvariablen

Variable Standard Beschreibung
HR_OPENREGISTER_API_KEY "" OpenRegister.de API-Key (empfohlen, kostenlos)
HR_USE_OPENREGISTER true OpenRegister nutzen wenn Key vorhanden
HR_API_KEY "" handelsregister.ai API-Key (optional, kostenpflichtig)
HR_USE_PAID_UPGRADE true Bezahltes Upgrade nutzen wenn Key vorhanden
HR_FREE_RATE_LIMIT 60 Rate-Limit fuer handelsregister.de (Anfragen/Stunde)
HR_TIMEOUT 90 HTTP-Timeout in Sekunden
HR_LOG_LEVEL INFO Log-Level (DEBUG, INFO, WARNING, ERROR)

Datenquellen (3-Tier-Strategie)

Tier Quelle Kosten Daten
1 handelsregister.de Kostenlos, unlimitiert Firmenname, Register, Status
2 OpenRegister.de Kostenlos, 50 Calls/Monat + Gesellschafter, Geschaeftsfuehrer, Kapital, Gegenstand, Jahresabschluesse
3 handelsregister.ai Kostenpflichtig Premium-Vollzugriff

Der Server routet automatisch zur besten Quelle und eskaliert zur naechsten wenn Daten unvollstaendig sind.

Methode Reihenfolge Grund
search_company handelsregister.de → OpenRegister → HRAI Suche unlimitiert zuerst
get_company_details OpenRegister → HRAI → handelsregister.de Reichere Daten zuerst
get_company_officers OpenRegister → HRAI → handelsregister.de Gesellschafter mit Anteilen
get_handelsregister_auszug OpenRegister → HRAI → handelsregister.de Strukturierter Auszug
get_jahresabschluss OpenRegister → HRAI Nur API-Quellen (kein handelsregister.de)

Beispiele

Typische Anfragen an den KI-Assistenten:

  • "Suche nach der BMW AG im Handelsregister"
  • "Zeige mir die Unternehmensdaten der Muster GmbH in Muenchen"
  • "Wer sind die aktuellen Geschaeftsfuehrer der Beispiel AG?"
  • "Erstelle einen Handelsregisterauszug fuer die Firma XY"
  • "Welche Gesellschafter hat die ABC Holding GmbH?"
  • "Zeige mir den Jahresabschluss der Zalando SE fuer 2022"

Fehlerbehebung

Problem Loesung
Failed to spawn process: No such file or directory uv nicht im PATH. Nutze den vollen Pfad: which uv im Terminal ausfuehren und in der Config als "command" eintragen
Server verbindet, aber keine Ergebnisse handelsregister.de blockiert zu schnelle Anfragen. Der Server hat automatische Retries eingebaut
Keine Datenquelle verfuegbar bei Jahresabschluss get_jahresabschluss braucht einen OpenRegister API-Key
Rate-Limit bei OpenRegister Kostenloser Plan hat 50 Calls/Monat. Fuer mehr: kostenpflichtiger Plan auf openregister.de

Entwicklung

git clone https://github.com/EliaLesyk/mcp-handelsregister.git
cd mcp-handelsregister

# Dependencies installieren
uv sync --all-extras

# Tests ausfuehren
uv run pytest

# Mit Coverage
uv run pytest --cov=mcp_handelsregister

Lizenz

MIT

相关 MCP