io.github.p-meier/northdata-mcp

Official

by p-meier · Python

NorthData API for German company, owner, and financial data — with a built-in credit guard.

Access German company, owner, and financial data with credit risk assessment.

Topics

claude-skillhandelsregistermcpmodel-context-protocolnorthdatapypipython-cli

README.md6 KBView on GitHub

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

bash

# Shell usage
pipx install northdata-cli
export NORTHDATA_API_KEY=XXXX-XXXX
northdata suggest "Siemens" --pretty

# MCP server for Claude Desktop / Cursor / Claude Code
pipx install northdata-mcp
# then add the stdio server to your MCP client config
# (see northdata-mcp/README.md)

# Claude Skill — usage guidance for agents
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

code

                      ┌─────────────────────────────────────────┐
                      │         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

bash

git clone https://github.com/p-meier/northdata-connectors.git
cd northdata-connectors

# CLI
cd northdata-cli && python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" && pytest

# MCP
cd ../northdata-mcp && python -m venv .venv && source .venv/bin/activate
pip install -e "../northdata-cli" -e ".[dev]" && pytest

License

MIT. See LICENSE.

Install

Configuration

Environment variables

NORTHDATA_API_KEYrequiredsecret

Your NorthData API key. Obtain one at https://www.northdata.com

NORTHDATA_APPROVAL_THRESHOLD

Power-search 'limit' above this requires approve_high_cost=true. Default: 25.

NORTHDATA_ABSOLUTE_MAX

Hard ceiling for power-search 'limit'. Default: 100. Flag-immune.

NORTHDATA_CREDIT_LOG

Path to the local credit log file. Default: ~/.northdata/credits.jsonl

claude_desktop_config.json

{
  "mcpServers": {
    "northdata-mcp": {
      "command": "uvx",
      "args": [
        "northdata-mcp"
      ],
      "env": {
        "NORTHDATA_API_KEY": "<YOUR_NORTHDATA_API_KEY>",
        "NORTHDATA_APPROVAL_THRESHOLD": "<YOUR_NORTHDATA_APPROVAL_THRESHOLD>",
        "NORTHDATA_ABSOLUTE_MAX": "<YOUR_NORTHDATA_ABSOLUTE_MAX>",
        "NORTHDATA_CREDIT_LOG": "<YOUR_NORTHDATA_CREDIT_LOG>"
      }
    }
  }
}