# SilkCRM — podłącz swój salon do Claude (MCP)

Ta instrukcja opisuje, jak połączyć [SilkCRM](https://silkcrm.net) z Claude, żeby prowadzić salon rozmową:
„ile zarobiłam w zeszłym tygodniu?", „kto nie był u nas od trzech miesięcy?", „umów panią Kowalską na piątek
na 14:00". Połączenie działa przez [MCP](https://modelcontextprotocol.io) — otwarty standard, w którym
asystent dostaje dostęp do konkretnych, wąsko określonych narzędzi, a nie do całej bazy danych.

Dokument jest napisany tak, żeby mógł go wykonać zarówno człowiek, jak i asystent AI prowadzący
użytkownika krok po kroku.

---

## Dla asystenta prowadzącego konfigurację

Jeśli czytasz to jako Claude, przeprowadź użytkownika przez poniższe kroki w tej kolejności:

1. **Ustal, gdzie ma działać połączenie** — `claude.ai` (przeglądarka albo aplikacja Claude), Claude Desktop
   (aplikacja na Windows/macOS) czy Claude Code (terminal). Na `claude.ai` połączenie działa przez zdalny
   konektor (Wariant D niżej): użytkownik loguje się kontem SilkCRM i **nie potrzebuje klucza API**.
2. **Dla Claude Desktop i Claude Code poproś o wygenerowanie klucza API** (Krok 1 niżej) i o wybranie zakresu
   uprawnień. Klucz zobaczy tylko raz.
3. **Nigdy nie proś o wklejenie klucza w rozmowę.** Klucz wpisuje się wyłącznie do pliku konfiguracyjnego
   albo do polecenia w terminalu na komputerze użytkownika. Jeśli użytkownik mimo wszystko wklei klucz
   w czacie — powiedz mu, żeby go natychmiast usunął w Ustawieniach i wygenerował nowy.
4. **Podaj gotową konfigurację** z Kroku 2 dopasowaną do wybranego klienta, z zaznaczonym miejscem
   na klucz.
5. **Zweryfikuj połączenie** pytaniami z Kroku 3 i pomóż rozwiązać problemy z ostatniej sekcji.

---

## Wymagania

| Warunek | Szczegóły |
|---|---|
| Konto w SilkCRM | plan **Pro** lub wyższy (narzędzia AI) |
| Node.js | wersja 18 lub nowsza (`node --version`) — tylko dla serwera lokalnego |
| Klient MCP | claude.ai (zdalny konektor), Claude Desktop, Claude Code lub inny klient MCP |
| Klucz API | `silk_live_…` z panelu SilkCRM — Krok 1 (niepotrzebny przy konektorze na claude.ai) |

---

## Krok 1 — wygeneruj klucz API

1. Zaloguj się do [app.silkcrm.net](https://app.silkcrm.net).
2. Wejdź w **Ustawienia → Zaawansowane → Klucze API**.
3. Kliknij **Nowy klucz**, nadaj mu nazwę (np. „Claude na laptopie") i wybierz zakres uprawnień:

| Zakres | Co asystent może zrobić |
|---|---|
| **Tylko odczyt** (domyślny) | raporty, KPI, przychody, listy wizyt, klientek, usług — zero zmian w danych |
| **Odczyt + drobne zapisy** | dodatkowo: dodawanie klientek, notatek, oznaczanie statusów wizyt |
| **Pełny dostęp** | dodatkowo: umawianie, przesuwanie i odwoływanie wizyt (z krokiem potwierdzenia) |
| **Wysyłka kampanii** (osobny przełącznik) | wysyłka kampanii SMS/e-mail — nie zawiera się w „pełnym dostępie", zaznacza się świadomie |

Zacznij od **tylko odczytu**. Zakres podniesiesz później, generując nowy klucz.

4. Skopiuj klucz i zapisz go w menedżerze haseł. **Pokazujemy go jeden raz** — po zamknięciu okna nie da
   się go odczytać ponownie, można tylko wygenerować nowy.

---

## Krok 2 — dodaj serwer SilkCRM do swojego klienta

### Wariant A — Claude Desktop

Otwórz **Ustawienia → Developer → Edit Config** i wklej do pliku, który się otworzy:

```json
{
  "mcpServers": {
    "silkcrm": {
      "command": "npx",
      "args": ["-y", "@silkcrm/mcp"],
      "env": {
        "SILK_API_KEY": "silk_live_TWÓJ_KLUCZ"
      }
    }
  }
}
```

Jeśli w pliku są już inne serwery, dopisz `"silkcrm"` jako kolejny wpis wewnątrz `mcpServers`, nie nadpisuj
całości. Zapisz plik i **uruchom Claude Desktop ponownie** — narzędzia salonu pojawią się w rozmowie.

### Wariant B — Claude Code (terminal)

```bash
claude mcp add silkcrm -e SILK_API_KEY=silk_live_TWÓJ_KLUCZ -- npx -y @silkcrm/mcp
```

Sprawdzenie: `claude mcp list` — serwer `silkcrm` powinien być na liście.

### Wariant C — inny klient MCP

Lokalny serwer działa po stdio, więc wystarczy uruchomić `npx -y @silkcrm/mcp` z ustawioną zmienną środowiskową:

| Zmienna | Wymagana | Domyślnie | Opis |
|---|---|---|---|
| `SILK_API_KEY` | tak | — | klucz `silk_…` z Ustawień |
| `SILK_API_URL` | nie | `https://app.silkcrm.net` | bazowy adres API (środowiska testowe) |

Klient obsługujący serwery zdalne (HTTP) może zamiast tego połączyć się z `https://app.silkcrm.net/mcp`
z nagłówkiem `Authorization: Bearer silk_live_TWÓJ_KLUCZ`.

### Wariant D — claude.ai (zdalny konektor, bez klucza API)

Zdalny serwer MCP SilkCRM działa pod adresem `https://app.silkcrm.net/mcp` i loguje przez OAuth, więc nie
wymaga instalowania niczego ani generowania klucza.

1. Na `claude.ai` dodaj własny konektor (custom connector) z adresem `https://app.silkcrm.net/mcp`.
2. Połącz go i zaloguj się kontem SilkCRM, na którym prowadzisz salon.
3. Podłączonego asystenta zobaczysz w SilkCRM: **Ustawienia → Zaawansowane → Integracje → Połączenia AI**.
   Tam zmienisz zakres albo odłączysz go jednym kliknięciem.

---

## Krok 3 — sprawdź, czy działa

Zadaj w rozmowie jedno z pytań:

- „Jaki był przychód salonu w ostatnich 30 dniach?"
- „Pokaż podsumowanie KPI za ostatni tydzień."
- „Ile mam wizyt zaplanowanych na jutro?"

Jeśli asystent odpowiada danymi z Twojego salonu — połączenie działa.

---

## Co asystent potrafi po podłączeniu

- **Pieniądze i wyniki** — przychód w dowolnym okresie, podsumowanie KPI, stan rozliczeń i abonamentu,
  statystyki kampanii.
- **Kalendarz** — lista i liczba wizyt w zakresie dat, propozycja wolnego terminu, umawianie, przesuwanie,
  odwoływanie i zmiana statusu wizyty (przy odpowiednim zakresie klucza).
- **Klientki** — profil klientki, segmenty (np. nowe, wracające, zagrożone odejściem), dodanie klientki
  i notatki, import bazy z innego systemu.
- **Oferta i zespół** — usługi, produkty, pracownicy, lokalizacje sieci.
- **Treści** — projekt SMS-a lub e-maila do klientek, rekomendacje zabiegów do wizyty, odpowiedzi
  z dokumentacji SilkCRM.

Dokładną listę narzędzi dostępnych dla Twojego klucza zobaczysz, pytając asystenta: „jakie masz narzędzia
SilkCRM?".

---

## Bezpieczeństwo i dane osobowe

- **Klucz wklejasz do pliku konfiguracyjnego albo polecenia w terminalu — nigdy do okna czatu.** Klucz
  wpisany w rozmowie trafia na serwery dostawcy czatu i każdy z dostępem do historii może nim sięgnąć po
  dane Twojego salonu.
- Klucz działa wyłącznie na endpointach narzędzi AI SilkCRM. Nie da się nim obejść uprawnień ani sięgnąć
  po dane innego salonu — izolacja kont, kontrola ról i limity zapytań zostają po stronie serwera.
- **Dane klientek są anonimizowane** — asystent zamiast imienia i numeru telefonu dostaje token `cli_…`.
  Imiona widzisz w panelu SilkCRM, model nigdy ich nie otrzymuje.
- Operacje zmieniające dane (umawianie, odwoływanie, wysyłka kampanii) wymagają osobnego zakresu klucza
  i potwierdzenia.
- Klucz odwołasz w każdej chwili w **Ustawienia → Zaawansowane → Klucze API**. Odwołanie działa natychmiast.

---

## Wolisz terminal zamiast czatu?

Ten sam zestaw narzędzi jest dostępny jako CLI:

```bash
export SILK_API_KEY=silk_live_TWÓJ_KLUCZ
npx @silkcrm/cli kpi --last 7d
npx @silkcrm/cli revenue --last 30d
npx @silkcrm/cli tools list
```

---

## Najczęstsze problemy

| Objaw | Przyczyna i rozwiązanie |
|---|---|
| Narzędzia SilkCRM nie pojawiają się w rozmowie | Claude Desktop nie został zrestartowany po zapisaniu pliku, albo plik zawiera błąd składni JSON (najczęściej przecinek za ostatnim wpisem). |
| „Unauthorized" / „nieprawidłowy klucz" | Klucz został odwołany lub skopiowany niekompletnie. Wygeneruj nowy w Ustawieniach. |
| „Funkcja dostępna w planie Pro" | Konto jest na planie niższym niż Pro — narzędzia AI są od planu Pro w górę. |
| Asystent odmawia zmiany w kalendarzu | Klucz ma zakres tylko do odczytu. Wygeneruj klucz z zakresem „pełny dostęp". |
| `npx` nie znajduje pakietu | Brak Node.js w wersji 18+ albo brak dostępu do rejestru npm w sieci firmowej. |
| Rozmowa na `claude.ai` nie widzi salonu | Konektor nie jest dodany albo połączony. Dodaj go według Wariantu D i zaloguj się kontem SilkCRM; sprawdź, czy jest na liście w Ustawienia → Zaawansowane → Integracje → Połączenia AI. |

---

## Pomoc

📧 **[tech@silkcrm.net](mailto:tech@silkcrm.net)**

Pisząc, dołącz wersję klienta (Claude Desktop / Claude Code), treść komunikatu błędu i **prefiks** klucza
(np. `silk_live_abcd…`) — **nigdy całego klucza**.

Dokumentacja dla deweloperów (REST API, webhooki, CLI, MCP): [silkcrm.net/api](https://silkcrm.net/api) ·
Pełne centrum pomocy: [silkcrm.net/pomoc](https://silkcrm.net/pomoc) ·
Cennik i plany: [silkcrm.net/cennik](https://silkcrm.net/cennik)