Metadata-Version: 2.4
Name: getsonar-mcp
Version: 0.1.2
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

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.

## What it does

Tools for:

- **KYB compliance** — corporate registries, sanctions screening (OFAC/UN/EU/UK), FCA Register lookup, directors, UBOs, 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 $20 at [getsonar.report/api-keys](https://getsonar.report/api-keys).

## 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 $20 once you've used your three free trial calls

## Install

### 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/api-keys](https://getsonar.report/api-keys).

**`402 Payment Required`** — your 3 free trial calls are used up and your balance is $0. Top up at [getsonar.report/api-keys](https://getsonar.report/api-keys).

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

## License

MIT — see [LICENSE](LICENSE).
