NorthData Companion Skill
This skill is the best-practice guide for working with the NorthData API through either:
northdata CLI — a command-line tool, typically used in Claude Code or a terminal.- 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:
| Check | Available? |
|---|
MCP tools named suggest, company, person, … | Use MCP. |
northdata on $PATH (try which northdata or northdata --version) | Use CLI. |
| Neither | Ask 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:
| Tier | Default | How to relax |
|---|
Approval threshold — limit > 25 needs --approve-high-cost (CLI) or approve_high_cost=true (MCP) | 25 | NORTHDATA_APPROVAL_THRESHOLD env |
| Absolute maximum — hard cap, flag-immune | 100 | 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)
- Start free.
suggest, reference_*, billing — zero credits. Use them to find the right company / confirm register IDs / check remaining quota before committing.
- 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.
- 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.
- 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
| Purpose | CLI | MCP |
|---|
| Autocomplete a name | northdata suggest "Example GmbH" | suggest |
| Current period usage | northdata billing | billing |
| API reference (standards, countries, …) | northdata reference overview | reference_overview |
| Segment codes for a standard | northdata reference segments --standard NACE2025 | reference_segment_codes |
| Local (session) credit log | northdata credits | local_credit_log |
Billed tools
| Purpose | CLI | MCP | Cost |
|---|
| Full company profile | northdata company --name "X" --city "Y" or --register "HRB 1/München" | company | 1 |
| Person lookup (birth date, roles) | northdata person Max Mustermann --city München | person | 1 |
| Publications (e.g. Gesellschafterliste) | northdata publications --name "X" --source Hrb | publications | 1 |
| Power search (filtered) | northdata search --segment-codes 62 --legal-forms GmbH --limit 5 | search | up to limit |
All billed tools accept --dry-run / dry_run=true.
Common workflows
"Find Company X and tell me about it"
suggest "Company X" (free) — pick the right one if multiple.company --register "<register from suggest>" or --name "<exact name>" --city "<city>" (1 credit).- 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):
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:
suggest first — copy the exact register.id (e.g. "HRB 296816") and register.uniqueKey from the response.- 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
| Var | Purpose |
|---|
NORTHDATA_API_KEY | API key (required) |
NORTHDATA_APPROVAL_THRESHOLD | Raises the soft threshold (default 25) |
NORTHDATA_ABSOLUTE_MAX | Raises the hard ceiling (default 100) |
NORTHDATA_CREDIT_LOG | Overrides local log location |
When the user is stuck
| Symptom | Likely cause | Fix |
|---|
No API key found | NORTHDATA_API_KEY not set | Export it, or (CLI) pass --api-key |
credit-guard: limit=X exceeds APPROVAL_THRESHOLD | High --limit without opt-in | Lower limit or add --approve-high-cost |
credit-guard: limit=X exceeds ABSOLUTE_MAX | Above hard cap | Split into paginated calls via pos, or raise env var |
api error: HTTP 429 | Rate-limited | Wait, retry later. Client already retries once. |
api error: HTTP 404 on company | Bad register ID or unknown name | Use suggest first to get canonical identifiers |
| Tools not visible in Claude Desktop | MCP server not registered or Claude not fully restarted | Check ~/Library/Application Support/Claude/claude_desktop_config.json; fully quit with ⌘Q |
Resources
