Metadata-Version: 2.4
Name: cardinal-mcp
Version: 0.2.0
Summary: MCP server for the Cardinal universal entity data API. Drop-in for Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-aware AI agent.
Author: Cardinal Labs
License: MIT
Project-URL: Homepage, https://cardinal.dev
Project-URL: Documentation, https://cardinal.dev/docs
Project-URL: Source, https://github.com/cardinal-labs/cardinal-mcp
Keywords: mcp,model-context-protocol,ai-agents,kyb,kyc,compliance,sanctions,regtech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27

# cardinal-mcp

Drop-in MCP server for the [Cardinal](https://cardinal.dev) universal entity
data API. Plug Cardinal into any MCP-aware AI agent — Claude Desktop, Claude
Code, Cursor, Windsurf, custom agents — and they can query Europe's entity
universe natively without writing a line of HTTP code.

## Install

```bash
pip install cardinal-mcp
```

## Configure

Set two env vars and point your MCP client at the binary.

```bash
export CARDINAL_API_KEY="cardinal_live_..."   # get one at cardinal.dev
export CARDINAL_BASE_URL="https://api.cardinal.dev"   # optional, default
```

### Claude Desktop / Claude Code

`~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cardinal": {
      "command": "cardinal-mcp",
      "env": {
        "CARDINAL_API_KEY": "cardinal_live_...",
        "CARDINAL_BASE_URL": "https://api.cardinal.dev"
      }
    }
  }
}
```

### Cursor / Windsurf

Add the same `mcpServers` block to your editor's MCP config. Both editors
read the same shape as Claude Desktop.

### Custom agent

Run `cardinal-mcp` as a stdio subprocess and speak JSON-RPC 2.0 over its
stdin/stdout. Wire-compatible with MCP 2025-06-18.

## Tools exposed

| Tool                       | What it does                                                   |
| -------------------------- | --------------------------------------------------------------- |
| `search_entities`          | Search by name + country + status + kind                        |
| `get_entity`               | Full entity record by Cardinal ID                               |
| `lookup_by_registry`       | Lookup by native registry id (orgnr, business id, ...)          |
| `get_entity_risk_summary`  | AI-generated compliance briefing                                |
| `search_court_records`     | Bankruptcies, judgments, enforcement actions                    |
| `search_officers`          | Cross-entity officer / director / owner search                  |
| `natural_language_query`   | Plain-English question → structured query → rows + summary      |

## License

MIT.
