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:

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:

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

Billed tools

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):

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

When the user is stuck

Resources

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