Metadata-Version: 2.4
Name: getsonar-mcp
Version: 0.1.9
Summary: MCP server for SONAR — KYB due diligence, competitive intelligence, and strategic accounts research for AI agents.
Project-URL: Homepage, https://getsonar.report
Project-URL: Documentation, https://getsonar.report/developers
Project-URL: API Reference, https://api.getsonar.report/docs
Project-URL: Support, https://getsonar.report/api-keys
Author-email: SONAR <ivan.vakulenko@wildix.com>
License-Expression: MIT
License-File: LICENSE
Keywords: adverse-media,anthropic,claude,competitive-intelligence,compliance,kyb,mcp,model-context-protocol,osint
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: http
Requires-Dist: uvicorn>=0.30.0; extra == 'http'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.Ivanolegvak/sonar-mcp -->

# getsonar-mcp

[![PyPI version](https://img.shields.io/pypi/v/getsonar-mcp.svg)](https://pypi.org/project/getsonar-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-4f46e5)](https://registry.modelcontextprotocol.io/v0/servers/io.github.Ivanolegvak%2Fsonar-mcp/versions)

MCP server for [SONAR](https://getsonar.report) — **KYB due diligence**, **competitive intelligence**, and **strategic accounts research** for AI agents.

Works with **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, **Continue.dev**, and any other [Model Context Protocol](https://modelcontextprotocol.io) client.

Published to the official MCP Registry as `io.github.Ivanolegvak/sonar-mcp` — discoverable by every MCP-aware client.

## What it does

Tools for:

- **KYB compliance** — corporate registries (15 jurisdictions), sanctions + PEP screening across ~300 lists via OpenSanctions plus native OFAC / UN / UK OFSI / Swiss SECO, **ICIJ Offshore Leaks** (Panama Papers, Paradise Papers, Pandora Papers, Bahamas Leaks), **UK Disqualified Directors register**, **The Gazette UK** (insolvency notices), **FCA Register** (UK financial authorisation), **EPA ECHO** (US environmental compliance), directors, UBOs, 10-year adverse media
- **Competitive intelligence** — pricing changes, hiring signals, product updates, customer sentiment, corporate events
- **Strategic accounts research** — buying signals, trigger events
- **Async narrated reports** — `/run` calls return AI-narrated reports written by Claude (compliance-officer-ready)

Two call shapes per agent:

- **`/findings`** — fast structured signals (~30-90s sync). Use when your agent will do its own analysis.
- **`/run`** — full report with Claude analysis (~3 min async, returns a `run_id` you poll).

**Pricing:** new accounts get **3 free trial calls** (any endpoint, lifetime — not monthly). After that:

| Endpoint | Price |
|---|---|
| `/findings` (any agent) | €0.40 |
| `/run` (any agent) | €2.00 |

Top up your account from **€5** at [getsonar.report/developer/keys](https://getsonar.report/developer/keys), or pick a monthly plan at [getsonar.report/settings](https://getsonar.report/settings).

## Get an API key

1. Sign up at [getsonar.report](https://getsonar.report)
2. Go to **API Keys** in the sidebar
3. Click **Create API Key**, copy the `sk-sonar-...` key
4. (Optional) Top up your account balance from €5 once you've used your three free trial calls

## Use without an MCP client (plain HTTP)

Don't need an MCP integration? Hit the SONAR API directly with curl, Python, JavaScript, or any HTTP client. The MCP server is just a thin wrapper over these endpoints.

### Quickstart with curl

```bash
# 1. Set your key
export SONAR_API_KEY=sk-sonar-...

# 2. Fast structured findings — sync, ~30-90s, €0.40 per call
curl -X POST 'https://api.getsonar.report/v1/agents/company-intelligence/findings' \
  -H "X-API-Key: $SONAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"company_name":"Stripe","website":"https://stripe.com"}'

# 3. Full AI-narrated report — async, ~3 min, €2.00 per call
curl -X POST 'https://api.getsonar.report/v1/agents/company-intelligence/run' \
  -H "X-API-Key: $SONAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"company_name":"Stripe","website":"https://stripe.com"}'
# → returns {"run_id": "...", "status": "queued"}

# 4. Poll the status until status="completed"
curl 'https://api.getsonar.report/v1/agents/company-intelligence/runs/RUN_ID' \
  -H "X-API-Key: $SONAR_API_KEY"
```

### Available agents

Replace `company-intelligence` in the URL with any of these:

| Agent | Use case |
|---|---|
| `company-intelligence` | Competitive intelligence — pricing, hiring, product, news |
| `kyb-diligence` | KYB / AML compliance — registries, sanctions, UBOs, adverse media |
| `strategic-accounts` | B2B sales research — buying signals, trigger events |
| `adverse-media` | Targeted negative-news screening across 8 languages |

### Account & balance

```bash
# Check balance + remaining free trial calls
curl 'https://api.getsonar.report/v1/account' -H "X-API-Key: $SONAR_API_KEY"
```

### Tips

- **Always include `website`** — the URL disambiguates generic-noun company names ("Stripe", "Apple", "Square") from unrelated entities sharing the brand word. Without a website, results may include irrelevant news collisions.
- **`/findings` is cheap and synchronous.** Use it when your downstream agent will do its own reasoning.
- **`/run` is the full report.** Async-only — submit, poll the run-id endpoint, expect ~3 min.
- **Free trial:** 3 calls of any kind, lifetime. After that the per-call price kicks in from your prepaid balance (top-up flow at `/developer/keys`) or your monthly subscription quota.
- **SSRF guard:** the `website` field must be `http://` or `https://` — unscoped strings, file://, and private IPs are rejected with HTTP 400.
- **Pretty output:** append `?pretty=1` to any endpoint URL for indented JSON during terminal exploration (e.g. `/v1/usage?pretty=1`). Default is compact for bandwidth.

Full OpenAPI spec at [api.getsonar.report/docs](https://api.getsonar.report/docs).

---

## Install (MCP server)

### Recommended: `uvx` (no install needed)

If you have [`uv`](https://docs.astral.sh/uv/) installed (most modern Python setups), nothing to install — `uvx getsonar-mcp` runs the latest version on demand.

### Alternative: `pipx`

```bash
pipx install getsonar-mcp
```

## Configure your MCP client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "sonar": {
      "command": "uvx",
      "args": ["getsonar-mcp"],
      "env": {
        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
      }
    }
  }
}
```

Restart Claude Desktop. The 7 tools should appear in the 🔌 menu.

### Claude Code

Add to your project's `.mcp.json` or run:

```bash
claude mcp add sonar -- uvx getsonar-mcp
# Then in your shell: export SONAR_API_KEY=sk-sonar-...
```

Or with the env var inline:

```bash
claude mcp add sonar --env SONAR_API_KEY=sk-sonar-... -- uvx getsonar-mcp
```

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "sonar": {
      "command": "uvx",
      "args": ["getsonar-mcp"],
      "env": {
        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
      }
    }
  }
}
```

### Windsurf / Continue.dev

Same config shape as Claude Desktop. See your client's MCP docs for the config file path.

## Configuration

Environment variables (all optional except `SONAR_API_KEY`):

| Variable | Default | Purpose |
|---|---|---|
| `SONAR_API_KEY` | (required) | Your `sk-sonar-...` API key |
| `SONAR_API_BASE` | `https://api.getsonar.report` | Override for staging / self-hosted SONAR |
| `SONAR_API_TIMEOUT` | `120` | Per-request timeout in seconds |
| `SONAR_MCP_LOG_LEVEL` | `INFO` | `DEBUG` for verbose tool dispatch logs |

## Example prompts

After configuring, try these in Claude:

> "Run a KYB check on Tesco PLC and tell me if anything looks risky."
>
> Claude calls `kyb_findings("Tesco PLC")` → ~30s → reads back the structured findings → highlights the FCA Register hit, any sanctions matches, director-level red flags.

> "Submit a full competitive analysis for Notion and tell me when it's done."
>
> Claude calls `competitive_run_submit("Notion")` → gets `run_id` → polls `check_report_status` every 30s → returns the narrative report.

> "How many free trial calls do I have left?"
>
> Claude calls `account_balance()` → tells you your current balance and how many of your three lifetime free trial calls remain.

## How async reports work

The `*_run_submit` tools return a `run_id` immediately (in <1s). Claude then needs to call `check_report_status(run_id, agent_type)` to fetch the result, which is normally ready in 60-180s. Most MCP clients handle this seamlessly — Claude knows from the tool descriptions to poll until status="completed".

The cheaper `*_findings` tools are synchronous and complete in 30-90s on a single call. Use those when the LLM just needs raw structured data and will do its own analysis.

## Verify your install

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to confirm the server starts and tool dispatch works:

```bash
SONAR_API_KEY=sk-sonar-... npx @modelcontextprotocol/inspector uvx getsonar-mcp
```

You should see all 7 tools listed and be able to invoke them with test inputs.

## Source

`getsonar-mcp` is a thin client for the SONAR public API. The source is currently maintained privately; for issues, feature requests, or transport changes, email **ivan.vakulenko@wildix.com**.

Maintainers: see [ARCHITECTURE.md](./ARCHITECTURE.md) for the internal module layout, the OAuth 2.0 flow, and the relationship between the stdio (`uvx getsonar-mcp`) and HTTP (`python -m getsonar_mcp.http_server`) transports.

## Troubleshooting

**Claude says "tool not available"** — check `claude_desktop_config.json` is valid JSON, restart Claude Desktop, then verify `uvx --version` runs in your terminal.

**`401 Unauthorized`** — `SONAR_API_KEY` is missing or wrong. Verify in the SONAR dashboard at [getsonar.report/developer/keys](https://getsonar.report/developer/keys).

**`402 Payment Required`** — your 3 free trial calls are used up and your balance is €0. Top up from €5 at [getsonar.report/developer/keys](https://getsonar.report/developer/keys), or pick a monthly plan at [getsonar.report/settings](https://getsonar.report/settings).

**Timeouts** — bump `SONAR_API_TIMEOUT` in your env config. The `/run` tools can take 3+ minutes for complex KYB subjects.

**`uvx getsonar-mcp` runs an old cached version** — uvx aggressively caches resolved environments. Force a refresh with one of:

```bash
uvx --refresh getsonar-mcp@<latest>      # pin the version
uv cache clean getsonar-mcp && uvx getsonar-mcp   # wipe + reinstall
```

**`TypeError: FastMCP.__init__() got an unexpected keyword argument 'description'`** — you're on a pre-0.1.6 cached version. Upgrade with `uv cache clean getsonar-mcp` then `uvx getsonar-mcp`.

**Wrong-entity news in results** — make sure you're passing `website` in your request body. Single-noun brand names ("Stripe", "Apple") collide with unrelated entities on Google News. SONAR drops collisions automatically when the website is supplied.

## License

MIT — see [LICENSE](LICENSE).
