NorthData Companion Skill#

This skill is the best-practice guide for working with the NorthData API through either:

1. northdata CLI — a command-line tool, typically used in Claude Code or a terminal.
2. NorthData MCP server — a set of tools exposed over the Model Context Protocol, typically used in Claude Desktop / Cursor / other MCP clients.

Both surfaces are built on the same NorthDataClient and share the same credit-guard discipline. Pick whichever is available in the current environment — this skill covers both.

Detect what's available#

Before deciding, check what's reachable:

CheckAvailable?MCP tools named suggest, company, person, …Use MCP.northdata on $PATH (try which northdata or northdata --version)Use CLI.NeitherAsk the user to install — point at northdata-cli (pipx) and/or the MCP server config.

If both are available: prefer MCP when running inside an MCP-aware client (clearer tool telemetry, structured errors). Prefer CLI in Claude Code or any shell-driven context.

The one rule you must internalize#

NorthData charges per returned company, not per HTTP call. A single search --limit 100 costs up to 100 credits in one go. Every billed call goes through the two-tier credit guard:

TierDefaultHow to relaxApproval threshold — limit > 25 needs --approve-high-cost (CLI) or approve_high_cost=true (MCP)25``NORTHDATA_APPROVAL_THRESHOLD envAbsolute maximum — hard cap, flag-immune100``NORTHDATA_ABSOLUTE_MAX env — set by a human, never by an agent

Never suggest raising either without a clear reason from the user.

Default workflow (use this order)#

1. Start free. suggest, reference_*, billing — zero credits. Use them to find the right company / confirm register IDs / check remaining quota before committing.
2. Dry-run anything billed. Both surfaces accept --dry-run (CLI) or dry_run=true (MCP). Use it first when parameters are uncertain — it builds the URL without calling the API.
3. One company call is usually enough. It returns owners, representatives, financials, sheets, events, contact extras. Don't also call publications or person unless you specifically need shareholder lists or a person's birth date.
4. Log watch. After billed calls, credits (CLI) / local_credit_log (MCP) shows what this session spent. billing shows what NorthData counts remotely.

Tool reference#

Free tools#

PurposeCLIMCPAutocomplete a namenorthdata suggest "Example GmbH"``suggestCurrent period usagenorthdata billing``billingAPI reference (standards, countries, …)northdata reference overview``reference_overviewSegment codes for a standardnorthdata reference segments --standard NACE2025``reference_segment_codesLocal (session) credit lognorthdata credits``local_credit_log

Billed tools#

PurposeCLIMCPCostFull company profilenorthdata company --name "X" --city "Y" or --register "HRB 1/München"``company1Person lookup (birth date, roles)northdata person Max Mustermann --city München``person1Publications (e.g. Gesellschafterliste)northdata publications --name "X" --source Hrb``publications1Power search (filtered)northdata search --segment-codes 62 --legal-forms GmbH --limit 5``searchup to limit

All billed tools accept --dry-run / dry_run=true.

Common workflows#

"Find Company X and tell me about it"#

1. suggest "Company X" (free) — pick the right one if multiple.
2. company --register "<register from suggest>" or --name "<exact name>" --city "<city>" (1 credit).
3. Done. Owners, representatives, financials, sheets, events all come back in one payload.

"Who owns / runs Company X?"#

company returns owners (Gesellschafter) and representatives (Geschäftsführer) in the same response. Don't chain multiple calls — one company call is enough.

For the birth date of a named person (e.g. succession planning), follow up with person --first-name … --last-name … --city … (1 credit).

"Find me companies matching these criteria"#

Use search (power search). Always:

• Set segment_codes (NACE) and legal_forms — an unfiltered search is expensive and rarely useful.
• Keep limit low (default 5). Only raise with explicit user approval.
• Use --dry-run first to sanity-check parameters.
• For geo-filters combine address + max_distance_km.
• Indicators: revenue_min/max, earnings_min/max narrow down the result set before spending credits.

Example (CLI):

bash

northdata search \
  --segment-codes "62|63" \
  --legal-forms "GmbH|UG" \
  --address "Munich" --max-distance-km 150 \
  --revenue-min 5000000 --revenue-max 50000000 \
  --limit 5 --dry-run

Verify the URL, then re-run without --dry-run.

Paginate via the pos token in the previous response's nextPos.

"Check if a register ID is valid before I spend a credit"#

suggest returns the canonical register.uniqueKey and register.id. That's free. Then pass --register to company exactly as shown.

"How many credits am I using?"#

• Remote total (period): billing
• This session only (local log): credits / local_credit_log

Common pitfalls#

HTTP 404 "not found" on company --register#

The register string must match NorthData's format. If "HRB 296816/München" returns 404, try:

1. suggest first — copy the exact register.id (e.g. "HRB 296816") and register.uniqueKey from the response.
2. Fall back to --name + --city — more forgiving than register matching.

Only numberOfRequests seems to count unique calls#

NorthData's billing endpoint returns unique requests per period. Repeated identical calls (same company, same day) don't increment the counter. The local credit log counts every attempted call regardless.

search with no segment filter#

Never run search with empty segment_codes and legal_forms. The credit guard allows it, but the cost/signal ratio is terrible. Always scope.

Umlauts in register strings#

URL-encoding is automatic in both surfaces. You can pass "München" directly — no manual percent-encoding needed.

--approve-high-cost / approve_high_cost=true#

Only set when the user has explicitly agreed to spend more. Never set preemptively "to make it work".

Environment knobs#

VarPurposeNORTHDATA_API_KEYAPI key (required)NORTHDATA_APPROVAL_THRESHOLDRaises the soft threshold (default 25)NORTHDATA_ABSOLUTE_MAXRaises the hard ceiling (default 100)NORTHDATA_CREDIT_LOGOverrides local log location

When the user is stuck#

SymptomLikely causeFixNo API key found``NORTHDATA_API_KEY not setExport it, or (CLI) pass --api-key``credit-guard: limit=X exceeds APPROVAL_THRESHOLDHigh --limit without opt-inLower limit or add --approve-high-cost``credit-guard: limit=X exceeds ABSOLUTE_MAXAbove hard capSplit into paginated calls via pos, or raise env varapi error: HTTP 429Rate-limitedWait, retry later. Client already retries once.api error: HTTP 404 on companyBad register ID or unknown nameUse suggest first to get canonical identifiersTools not visible in Claude DesktopMCP server not registered or Claude not fully restartedCheck ~/Library/Application Support/Claude/claude_desktop_config.json; fully quit with ⌘Q

Resources#

• NorthData API docs: https://github.com/northdata/api
• CLI package: northdata-cli/ (this repo)
• MCP server: northdata-mcp/ (this repo)