getsonar-mcp Server

getsonar-mcp 0.1.9

pip install getsonar-mcp

Latest release

Released: May 15, 2026

MCP server for SONAR — KYB due diligence, competitive intelligence, and strategic accounts research for AI agents.

Navigation

Verified details

These details have been verified by PyPI

Maintainers

getsonar.report

Unverified details

These details have not been verified by PyPI

Project links

• API Reference
• Documentation
• Homepage
• Support

Meta

• License Expression: MIT
  SPDX License Expression
• Author: SONAR
• adverse-media , anthropic , claude , competitive-intelligence , compliance , kyb , mcp , model-context-protocol , osint
• Requires: Python >=3.10
• Provides-Extra: http

Classifiers

• Development Status
  • 4 - Beta
• Intended Audience
  • Developers
• Programming Language
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
• Topic
  • Software Development :: Libraries

Project description

getsonar-mcp

MCP server for SONAR — 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 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, or pick a monthly plan at getsonar.report/settings.

Get an API key

1. Sign up at 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

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

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.

---

Install (MCP server)

Recommended: uvx (no install needed)

If you have uv installed (most modern Python setups), nothing to install — uvx getsonar-mcp runs the latest version on demand.

Alternative: pipx

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):

{ "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:

claude mcp add sonar -- uvx getsonar-mcp

Then in your shell: export SONAR_API_KEY=sk-sonar-...

Or with the env var inline:

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

Cursor

~/.cursor/mcp.json:

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 to confirm the server starts and tool dispatch works:

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 [email protected].

Maintainers: see 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.

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, or pick a monthly plan at 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:

uvx --refresh getsonar-mcp@ # 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.

Project details

Meta

Release history Release notifications | RSS feed

This version

0.1.9

May 15, 2026

0.1.8

May 9, 2026

0.1.7

May 9, 2026

0.1.6

May 6, 2026

0.1.5

May 5, 2026

0.1.4

May 4, 2026

0.1.3

May 3, 2026

0.1.2

May 3, 2026

0.1.0

Apr 28, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

getsonar_mcp-0.1.9.tar.gz (15.4 kB view details)

Uploaded May 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

getsonar_mcp-0.1.9-py3-none-any.whl (18.3 kB view details)

Uploaded May 15, 2026 Python 3

File details

Details for the file getsonar_mcp-0.1.9.tar.gz.

File metadata

• Download URL: getsonar_mcp-0.1.9.tar.gz
• Upload date: May 15, 2026
• Size: 15.4 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.2.0 CPython/3.11.5

File hashes

Algorithm	Hash digest
SHA256	7fe4a03740812762f9f23bd984b69b0bdb59c4da1fbe3bbad9350f957de6bca5	Copy
MD5	ffeaf47be1b65fdba48a424a04f4dd81	Copy
BLAKE2b-256	e1cb37d0437591e2381db33b3a71771891ae7ddbf6a2bb99e1a70a1e98c0367b	Copy

See more details on using hashes here.

File details

Details for the file getsonar_mcp-0.1.9-py3-none-any.whl.

• Download URL: getsonar_mcp-0.1.9-py3-none-any.whl
• Upload date: May 15, 2026
• Size: 18.3 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.2.0 CPython/3.11.5

File hashes

Algorithm	Hash digest
SHA256	4890283f45281cc7be8d02f1f988834ddc0a6b9da26fa7d68d51ead11eec7abb	Copy
MD5	9a7fc6f7caeb523c239cade6e73b4f74	Copy
BLAKE2b-256	92d4909690b080c7a52392599f927f00b4aee3bb22a07cf81a7a48383a2241fd	Copy

• English
• español
• français
• 日本語
• português (Brasil)
• українська
• Ελληνικά
• Deutsch
• 中文 (简体)
• 中文 (繁體)
• русский
• עברית
• Esperanto
• 한국어

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page