intent

use northdata to query german commercial registers (HRB, HRA), financial data, and person records. this skill covers both the northdata CLI (claude code / terminal) and the northdata MCP server (claude desktop / any MCP client). trigger on queries about specific german companies (GmbH, UG, KG), owner / geschäftsführer / gesellschafter lookups, revenue / earnings / balance sheet reads, NACE segment searches, geographic filters, credit usage checks, or power-searches for acquisition / lead candidates. use this skill when the user asks about "northdata", "handelsregister", "HRB", "HRA", "gesellschafter", "geschäftsführer", "firma recherchieren", or requests filtered company searches.

inputs

required external connections:

• NORTHDATA_API_KEY environment variable or --api-key CLI flag. obtain from northdata at https://github.com/northdata/api.
• northdata CLI: installed via pipx install northdata-cli (or available on $PATH).
• northdata MCP server: registered in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent (linux/windows).

optional environment knobs:

• NORTHDATA_APPROVAL_THRESHOLD (default: 25): soft credit threshold; queries with limit > threshold require --approve-high-cost flag.
• NORTHDATA_ABSOLUTE_MAX (default: 100): hard credit ceiling; queries above this fail unless env var is raised by a human operator.
• NORTHDATA_CREDIT_LOG: override local session credit log file location.

context the user provides:

• company name, city, or register ID (e.g., "HRB 296816/München").
• person name (first name, last name, city) for person lookups.
• search filters: NACE segment codes, legal form (GmbH, UG, KG, etc.), geographic bounds (address + radius), financial indicators (revenue min/max, earnings min/max).

procedure

step 1: detect available surface

check which tool surface is available in the current environment.

input: current shell / IDE / runtime.

action: in order:

• if running inside claude desktop or an MCP-aware client, check for MCP tools named suggest, company, person, search, publications, billing, reference_*, credits, or local_credit_log. if visible, go to step 2a (use MCP).
• if MCP tools are not visible, check if northdata command is on $PATH by running which northdata or northdata --version. if found, go to step 2b (use CLI).
• if neither is available, inform the user and provide setup guidance: CLI via pipx install northdata-cli, MCP server registration in claude desktop config.

output: decision: "use MCP" or "use CLI" or "not available, setup required".

step 2a: using MCP server (if available)

step 2a-i: free tools (zero credits)

call one of these to scope the query without spending credits:

• suggest(query="Company Name"): autocomplete and canonicalize a company name. returns multiple matches with register.id, register.uniqueKey, and name. use to pick the right entity if ambiguous.
• billing(): current period usage (remote, counted by northdata). shows total credits spent and remaining quota.
• local_credit_log(): this session's credit usage (local log). shows every call this session attempted.
• reference_overview(): list all available reference endpoints (standards, countries, segment codes).
• reference_segment_codes(standard="NACE2025"): fetch NACE segment codes for filtering.

input: user query or parameters.

output: structured response with matches, credits remaining, or reference data.

step 2a-ii: dry-run billed tools (zero credits, validates parameters)

before calling any billed tool, validate parameters with dry_run=true:

• company(name="...", city="...", register="...", dry_run=true): builds the request URL without calling the API. verify the output URL is correct.
• search(segment_codes="62|63", legal_forms="GmbH", address="Munich", max_distance_km=150, limit=5, dry_run=true): previews filter, does not charge.
• person(first_name="...", last_name="...", city="...", dry_run=true): previews person lookup.
• publications(name="...", register="...", source="Hrb", dry_run=true): previews publication search.

input: all parameters needed for the real call.

output: request URL and estimated structure, no API call made.

step 2a-iii: billed tools (charges 1 credit per company returned or 1 per person/publication)

• company(register="<ID>" or name="<name>", city="<city>", ...): returns single company profile with owners (gesellschafter), representatives (geschäftsführer), financials (revenue, earnings, balance sheet), published sheets, events, and contact extras. cost: 1 credit. always pass dry_run=true first if unsure about parameters.
• person(first_name="<>", last_name="<>", city="<>"): returns person record with birth date, roles, and linked companies. cost: 1 credit. use only if you need birth date or shareholder-level details not in company response.
• publications(name="<>", register="<>", source="Hrb|Hra|Default"): returns historical publications (e.g., gesellschafterliste, amendments). cost: 1 credit. use only if you need change history.
• search(segment_codes="62|63", legal_forms="GmbH|UG", address="<>", max_distance_km=<>, revenue_min=<>, revenue_max=<>, earnings_min=<>, earnings_max=<>, limit=<>, pos="<pagination token>"): filtered power search. cost: up to limit credits (one per company returned). always set segment_codes and legal_forms to narrow scope. start with limit=5, raise only with explicit user approval. use pos from previous response to paginate.

input: billed tool parameters, optionally approve_high_cost=true if limit > APPROVAL_THRESHOLD.

output: structured company / person / publication data or search result list.

step 2b: using CLI (if available)

step 2b-i: free commands (zero credits)

northdata suggest "Company Name"
northdata billing
northdata credits
northdata reference overview
northdata reference segments --standard NACE2025

input: query string or command flag.

output: YAML or JSON (depending on shell setup) with matches, credits, or reference data.

step 2b-ii: dry-run billed commands (zero credits, validates parameters)

northdata company --name "..." --city "..." --dry-run
northdata search --segment-codes "62|63" --legal-forms "GmbH" --address "Munich" --limit 5 --dry-run
northdata person --first-name "..." --last-name "..." --city "..." --dry-run
northdata publications --name "..." --source Hrb --dry-run

input: all flags and parameters for the intended call.

output: curl command and request URL, no API call made. verify URL before proceeding.

step 2b-iii: billed commands (charges 1 credit per company or person/publication)

# company lookup by register ID (preferred if register ID is known)
northdata company --register "HRB 296816/München"

# company lookup by name and city (more forgiving)
northdata company --name "Example GmbH" --city "Munich"

# person lookup (1 credit, returns birth date and roles)
northdata person --first-name "Max" --last-name "Mustermann" --city "Munich"

# publications (1 credit, returns historical versions)
northdata publications --name "Example GmbH" --source Hrb

# power search with filters (up to N credits, where N = limit)
northdata search \
  --segment-codes "62|63" \
  --legal-forms "GmbH|UG" \
  --address "Munich" --max-distance-km 150 \
  --revenue-min 5000000 --revenue-max 50000000 \
  --limit 5

if limit > NORTHDATA_APPROVAL_THRESHOLD (default 25), add --approve-high-cost.

input: command flags and parameters.

output: JSON or YAML response (check northdata --help for format options). if rate-limited (HTTP 429), wait and retry.

step 3: interpret results and follow-up

input: response from step 2a-iii or 2b-iii.

action:

• for a company call: extract owners (gesellschafter), representatives (geschäftsführer), revenue, earnings, balance sheet, and events from the single response. do not call person or publications unless user explicitly asks for birth dates or historical amendments.
• for a search call: list results with company names, registers, segments, and key indicators. if more results exist (indicated by nextPos in MCP or pos in CLI output), ask the user before paginating (each page costs credits).
• for a person call: return birth date, roles, and linked companies.
• for a publications call: return publication dates, amendment text, and signature information.

output: curated company profile, search results, person details, or publication history.

step 4: credit hygiene

after any billed call:

• MCP: call local_credit_log() to see what this session spent. call billing() to see remote total (period usage as counted by northdata).
• CLI: run northdata credits for session log, northdata billing for period total.

if the user is surprised by the bill, check billing() output: northdata counts unique requests per period, not total calls. repeated identical calls (same company, same day) do not double-charge.

output: credit usage summary and remaining quota.

decision points

if MCP tools are visible and CLI is also on $PATH: prefer MCP. it provides clearer tool telemetry and structured error messages. only fall back to CLI if the user is inside a shell-driven context (e.g., debugging, bulk automation).

if dry_run=true (MCP) or --dry-run (CLI) returns an error: likely cause: bad parameter format or missing required field. do not proceed to the real call. ask the user to confirm the parameter (e.g., exact register ID format, NACE segment code syntax). call suggest or reference_segment_codes to validate.

if API returns HTTP 404 on a company call: the register string may not match northdata's format. do this in order:

1. call suggest(query="Company Name") and copy the exact register.id from the response.
2. retry company(register="<exact ID from suggest>").
3. if still 404, fall back to company(name="...", city="...") (more forgiving than register matching).

if API returns HTTP 429 (rate-limited): the session has exceeded rate limits. wait at least 60 seconds and retry. both MCP and CLI clients already retry once automatically. if repeated 429s occur, spread calls over multiple minutes or contact northdata support.

if limit > NORTHDATA_APPROVAL_THRESHOLD and no --approve-high-cost / approve_high_cost=true is set: the credit guard blocks the call. either lower limit (recommended: start with 5) or ask the user: "this search will cost up to N credits. approve?" if yes, add the flag and retry.

if limit > NORTHDATA_ABSOLUTE_MAX even with the flag: only a human operator can raise the hard ceiling via env var. inform the user: "this exceeds the hard limit. contact your account admin to raise NORTHDATA_ABSOLUTE_MAX." or suggest paginating via pos / pagination tokens across multiple smaller calls.

if the user asks "who owns / runs company X": a single company call returns both owners (gesellschafter) and representatives (geschäftsführer). do not call person or publications unless the user specifically needs birth dates or shareholder lists.

if the user asks for a person's birth date: call person(first_name="...", last_name="...", city="..."). this costs 1 credit and returns birth date, roles, and linked companies. this is only available if you have a specific person's name and approximate location.

if search has no segment-codes or legal-forms filter: do not run the search. the cost/signal ratio is terrible (high credits, low relevance). always scope with segment_codes and legal_forms before calling search. if the user is unsure, call reference_segment_codes(standard="NACE2025") to find the right codes.

if the user provides a register string with umlauts (e.g., "HRB 1/München"): both surfaces handle URL-encoding automatically. pass it as-is. do not manually percent-encode.

if NORTHDATA_API_KEY is not set: both MCP and CLI will fail with "no API key found". CLI accepts --api-key flag; MCP requires env var. ask the user to export the key or pass the flag.

output contract

successful company call (MCP or CLI):

• JSON or YAML object with fields: register.id, register.uniqueKey, name, city, legalForm, owners (array of gesellschafter with names and roles), representatives (array of geschäftsführer), financials (object with revenue, earnings, balance sheet lines), sheets (published financial statements), events (register amendments and filings), contact (phone, email, website if available).
• file location: stdout (CLI) or structured MCP response object.

successful person call:

• JSON or YAML object with fields: firstName, lastName, birthDate (if available), roles (array of company roles and titles), linkedCompanies (array of company registers).
• file location: stdout or MCP response.

successful search call:

• JSON or YAML object with fields: results (array of company summaries, each with register.id, name, city, legalForm, segment, revenue, earnings), totalCount (total matching companies, may exceed limit), nextPos (pagination token for next page if results exist).
• file location: stdout or MCP response.

successful suggest call:

• JSON or YAML array of matches, each with register.id, register.uniqueKey, name, city, status.
• file location: stdout or MCP response.

successful billing / credits call:

• JSON or YAML object with fields: creditsUsed (period or session total), creditsRemaining, creditsLimit, period (month/year for remote; session for local).
• file location: stdout or MCP response.

successful dry-run call:

• --dry-run or dry_run=true: returns request URL and estimated response structure; no charges incurred.
• file location: stdout or MCP response.

error responses:

• HTTP 404: company or person not found. include the register ID or name that was queried.
• HTTP 429: rate-limited. include retry-after header (if present).
• credit-guard error: limit exceeds threshold or absolute max. include current limit and threshold values.
• Missing API key: explicit message "no API key found. set NORTHDATA_API_KEY or pass --api-key".

outcome signal

the user knows the skill worked when:

1. company lookup: the response displays the company name, register ID, owners (gesellschafter) and representatives (geschäftsführer) with full names and roles, and financials (revenue, earnings, balance sheet extracts, fiscal year). the user can immediately answer "who runs this company?" and "what's their revenue?"

2. person lookup: the response shows the person's full name, birth date (or "not public"), and a list of companies they are linked to (as geschäftsführer, gesellschafter, etc.).

3. search result: the response lists 5 (or user-specified limit) companies matching all filters (NACE segments, legal forms, geographic bounds, financial ranges). each row shows company name, register ID, segment, city, and key indicators. user can click register links or copy IDs for follow-up company calls.

4. suggest autocomplete: the response returns the company name the user typed, plus alternative matches if ambiguous, each with a canonical register.id ready to paste into company --register.

5. billing / credits report: the response shows credits used (this session or period) and remaining quota. if the user spent credits, the report matches their expectation (e.g., 5 companies searched = 5 credits). if the user thought they ran 10 calls but the billing shows 2, they learn that duplicate calls don't double-charge.

6. --dry-run / dry_run=true preview: the response shows the exact URL that would be called and the expected response structure, with a clear message "no charges incurred". user can verify parameters before committing.

7. error recovery: if a call fails with HTTP 404 or a credit-guard block, the skill output includes the exact reason and the next step (e.g., "use suggest to get the canonical register ID", or "add --approve-high-cost and retry").