SoonaR MCP konektor

Pripojenie na SoonaR priamo do Claude Desktop. SoonaR je interný nástroj na hľadanie a spracovanie slovenských firiem ako obchodných leadov (register + financie + kontakty + CRM). Po pripojení dostaneš v Claude sadu nástrojov, ktoré vie volať priamo v chate.

Tento konektor je tenký klient - len zavolá SoonaR API cez sieť. Žiadna databáza, žiadne tajomstvá okrem tvojho API tokenu.

Čo budeš vedieť robiť (cez chat)

• Hľadať firmy podľa kritérií: sektor / NACE, kraj, obrat, tržby, zisk, medziročný rast, dlh.
• Pozrieť detail firmy vrátane konateľov (štatutárov) na kontaktovanie.
• Obohatiť kontakt (email/telefón cez Lusha).
• Pushnúť firmu do Odoo CRM + naplánovať hovor.
• Nájsť firmy, ktoré práve naberajú ľudí (z pracovných inzerátov).

Predpoklady

1. Claude Desktop (stiahni: https://claude.ai/download).
2. Git (https://git-scm.com/downloads). Na Windows nainštaluj "Git for Windows" s predvolenými nastaveniami. Slúži na stiahnutie tohto konektora cez git clone. (Ak Git nechceš, môžeš si repo stiahnuť aj ako ZIP - viď krok 1.)
3. Python 3.10+ (https://www.python.org/downloads/). Pri inštalácii na Windows zaškrtni "Add Python to PATH".
4. Tvoj API token - pošle ti ho admin (damia). Je to tvoj osobný kľúč, nezdieľaj ho.

1) Stiahni konektor

Možnosť A - Git (odporúčané): naklonuj repo, napr. do C:\Users\<ty>\soonar-mcp:

git clone <URL-tohto-repa> soonar-mcp

Možnosť B - bez Gitu: na stránke repa klikni Code -> Download ZIP, rozbaľ ho (napr. do C:\Users\<ty>\soonar-mcp).

2) Nainštaluj závislosti

V priečinku konektora spusti:

pip install -r requirements.txt

(nainštaluje mcp a httpx)

3) Pripoj do Claude Desktop (Edit Config)

1. Otvor Claude Desktop.
2. Choď do Settings -> Developer -> Edit Config. Otvorí sa súbor claude_desktop_config.json v tvojom editore.
3. Vlož tento blok (ak už mcpServers máš, len doň pridaj kľúč "soonar"). Uprav cestu k mcp_server.py a vlož svoj token:

{
  "mcpServers": {
    "soonar": {
      "command": "python",
      "args": ["C:\\Users\\TVOJE_MENO\\soonar-mcp\\mcp_server.py"],
      "env": {
        "SOONAR_API_URL": "https://soonar.zvar.it",
        "SOONAR_API_TOKEN": "VLOZ_SVOJ_TOKEN"
      }
    }
  }
}

4. Ulož súbor.

Poznámky k ceste a príkazu:

• Windows: v ceste daj dvojité spätné lomky \\ (ako vyššie).
• Ak python nefunguje, skús py, alebo daj plnú cestu k python.exe.
• macOS/Linux: "command": "python3" a cesta typu "/Users/ty/soonar-mcp/mcp_server.py".

Vzor je aj v súbore claude_desktop_config.example.json.

4) Reštartuj Claude Desktop

Úplne ho zavri a znova otvor. Po štarte uvidíš ikonu nástrojov (kladivko) a medzi nimi nástroje soonar.

5) Vyskúšaj v chate

• "koľko firiem máme v databáze?"
• "nájdi 10 IT firiem v Bratislave s obratom nad 1M a bez dlhu"
• "ukáž detail firmy s IČO 31333532"
• "ktoré firmy naberajú Python vývojárov?"
• "pridaj firmu s IČO 31333532 do CRM a naplánuj hovor o 3 dni"

Dôležité - kredity a zápisy

• enrich_contact (email/telefón cez Lusha) míňa kredity (~10 za telefón). Nástroj ti najprv ukáže odhad ceny a zostatok - over to pred potvrdením.
• push_lead / create_contacts zapisujú do Odoo CRM naozaj. Vždy si over, čo robíš.

Riešenie problémov

• Nástroje sa neukázali: skontroluj, či je claude_desktop_config.json validný JSON (čiarky, zátvorky), či sedí cesta k mcp_server.py, a reštartuj Claude Desktop.
• python not found / ENOENT: Python nie je na PATH. Daj plnú cestu k python.exe, alebo preinštaluj Python so zaškrtnutým "Add to PATH".
• 401 / invalid token: zlý alebo chýbajúci token. Skontroluj SOONAR_API_TOKEN.
• Connection error: over SOONAR_API_URL = https://soonar.zvar.it.

Kde je konfiguračný súbor (ak by "Edit Config" nešiel):

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json