NorthData Connectors
Generic, product-side wrapper around the NorthData API — a Python CLI, an MCP server, and a Claude Skill, sharing one credit guard.
Unofficial project. This repository is an independent, community-maintained wrapper around the NorthData API. It is not developed, endorsed, or supported by NorthData GmbH. "NorthData" is a trademark of its respective owner; all company data accessed through this tooling remains subject to NorthData's own terms of service. For the official API documentation, see github.com/northdata/api.
This monorepo ships three layers on top of the NorthData API:
| Package | What it is | Install |
|---|
northdata-cli | Command-line client. JSON-by-default, table with --pretty. Single source of API logic. | pipx install northdata-cli |
northdata-mcp | Model Context Protocol server exposing every CLI command as a tool. Works with Claude Desktop, Claude Code, Cursor, etc. | pipx install northdata-mcp |
skills/northdata | Claude Skill with usage guidance, credit-guard discipline, and endpoint cheat-sheet. | npx skills add p-meier/northdata-connectors |
All three share one credit guard because NorthData charges per returned company, not per HTTP call.
Why this exists
NorthData's API is the canonical source for German commercial-register data (company profiles, owners, representatives, financials, publications). This repo makes it trivial to consume that data from:
- Shell scripts and CI pipelines (
northdata search ...)
- AI agents in any MCP-capable client (Claude Desktop, Cursor, Claude Code, …)
- Claude Skills that want domain-aware guidance without duplicating API code
The three layers never duplicate logic — the CLI is the library, the MCP server imports it, the Skill references the MCP tools.
Quick start
1. Get a NorthData API key
At https://www.northdata.com. Set it as NORTHDATA_API_KEY.
2. Install what you need
pipx install northdata-cli
export NORTHDATA_API_KEY=XXXX-XXXX
northdata suggest "Siemens" --pretty
pipx install northdata-mcp
npx skills add p-meier/northdata-connectors
3. Credit-safe by default
Every billable call respects two tiers:
| Tier | Default | Env var |
|---|
| Approval threshold | 25 | NORTHDATA_APPROVAL_THRESHOLD |
| Absolute maximum | 100 | NORTHDATA_ABSOLUTE_MAX |
Use --dry-run (CLI) or dry_run=true (MCP) to inspect a request without spending credits.
Architecture
┌─────────────────────────────────────────┐
│ NorthData API (HTTP) │
└─────────────────────────────────────────┘
▲
│ httpx + Credit Guard
│
┌───────────────────────┐
│ northdata-cli │ ← single source of API logic
│ (Python library) │ (client, credit guard,
└───────────────────────┘ config, output)
▲ ▲
imports │ │ invokes
│ │
┌───────────────────────┐ ┌───────────────────────┐
│ northdata-mcp │ │ shell / CI / │
│ (FastMCP, stdio) │ │ scripts │
└───────────────────────┘ └───────────────────────┘
▲
│ MCP over stdio
│
┌───────────────────────┐
│ Claude / Cursor / │ ← with skills/northdata/SKILL.md
│ any MCP client │ loaded for usage guidance
└───────────────────────┘
The CLI holds the API logic; the MCP server is a thin wrapper; the Skill is documentation-as-code. All three share one credit guard.
Development
git clone https://github.com/p-meier/northdata-connectors.git
cd northdata-connectors
cd northdata-cli && python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" && pytest
cd ../northdata-mcp && python -m venv .venv && source .venv/bin/activate
pip install -e "../northdata-cli" -e ".[dev]" && pytest
License
MIT. See LICENSE.
Links