Skip to main content
Glama
esticrm-mcp

esticrm-mcp

Połącz EstiCRM z klientem MCP

Ten projekt uruchamia lokalny serwer Model Context Protocol (MCP), który udostępnia wybrane operacje EstiCRM w Codexie, Claude Code i Claude Desktop. Każda osoba używa własnego identyfikatora firmy oraz tokenu API, a narzędzia zapisujące dane pozostają domyślnie wyłączone.

WARNING

To projekt społecznościowy, nieoficjalny i niepowiązany z EstiCRM. Nie jest produktem, usługą ani integracją zatwierdzoną przez operatora EstiCRM. Przed użyciem na danych produkcyjnych sprawdź aktualne warunki usługi i zakres uprawnień swojego konta.

Co umożliwia serwer

Serwer tłumaczy polskie wywołania narzędzi MCP na ograniczony zestaw operacji APIClient EstiCRM. Działa lokalnie przez standardowe wejście i wyjście procesu (stdio), bez własnego serwera HTTP i bez wspólnego konta pośredniczącego.

Projekt obejmuje:

  • polskie nazwy, opisy i komunikaty narzędzi

  • bezpieczne ustawienia domyślne tylko do odczytu

  • maskowanie danych kontaktowych klienta w domyślnym widoku

  • walidację argumentów przed wysłaniem żądania

  • kontrolowany odstęp między żądaniami i limit czasu

  • rozpoznawanie błędu zwróconego przez EstiCRM z kodem HTTP 200

  • opcjonalne narzędzia zapisu wymagające jawnego włączenia

  • testy bez prawdziwych danych EstiCRM

Related MCP server: rd-station-crm

Wymagania przed instalacją

Do uruchomienia potrzebujesz:

  • Node.js 20.19 lub nowszego z linii 20 albo Node.js 22.12 lub nowszego, w tym Node.js 24

  • pnpm, najlepiej włączonego przez Corepack

  • konta EstiCRM z dostępem do API

  • własnych wartości ESTICRM_COMPANY_ID i ESTICRM_API_TOKEN

  • klienta obsługującego lokalne serwery MCP przez stdio

Dostępność poszczególnych operacji zależy od planu i uprawnień nadanych przez EstiCRM. Jeśli nie widzisz danych API w panelu, skontaktuj się z pomocą EstiCRM.

Zainstaluj projekt z GitHuba

Repozytorium możesz sklonować i zbudować lokalnie:

git clone https://github.com/flatmoonsociety/esticrm-mcp.git
cd esticrm-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm build

Projekt nie wymaga globalnej instalacji pakietu. Klient MCP uruchamia zbudowany plik dist/index.js przy każdym połączeniu.

Pakiet jest oznaczony jako prywatny dla rejestrów npm i nie jest przeznaczony do publikacji w npm. Współdzielenie projektu odbywa się przez to repozytorium GitHub.

Skonfiguruj dane dostępowe

Utwórz lokalny plik .env z dostarczonego wzoru i ogranicz jego uprawnienia:

cp .env.example .env
chmod 600 .env

W Windows PowerShell użyj Copy-Item .env.example .env i pomiń polecenie chmod.

Otwórz .env, a następnie zastąp dwa opisowe symbole zastępcze własnymi danymi:

ESTICRM_COMPANY_ID=wpisz_id_firmy
ESTICRM_API_TOKEN=wpisz_token_api
ESTICRM_ENABLE_WRITES=false
ESTICRM_TIMEOUT_MS=15000
ESTICRM_REQUEST_INTERVAL_MS=1100
ESTICRM_MAX_RESPONSE_BYTES=2097152
ESTICRM_MAX_ACTIVE_REQUESTS=25

Plik .env jest ignorowany przez Git. Nie przekazuj go innym osobom i nie dodawaj jego zawartości do zgłoszeń błędów.

Opcjonalne ustawienia mają następujące znaczenie:

Zmienna

Wartość domyślna

Działanie

ESTICRM_ENABLE_WRITES

false

Udostępnia narzędzia zapisujące po ustawieniu true

ESTICRM_TIMEOUT_MS

15000

Przerywa pojedyncze żądanie po podanej liczbie milisekund

ESTICRM_REQUEST_INTERVAL_MS

1100

Ustawia minimalny odstęp między żądaniami w milisekundach

ESTICRM_MAX_RESPONSE_BYTES

2097152

Ogranicza rozmiar treści pojedynczej odpowiedzi do podanej liczby bajtów, domyślnie 2 MiB

ESTICRM_MAX_ACTIVE_REQUESTS

25

Odrzuca nowe operacje, gdy liczba trwających i oczekujących wywołań osiągnie limit

Ustawienie zapisu akceptuje także 1 lub tak. Pozostaw false, jeśli potrzebujesz wyłącznie odczytu.

Połącz serwer z Codexem

Codex może zapisać konfigurację lokalnego serwera jednym poleceniem. Zastąp obie ścieżki pełną ścieżką do sklonowanego repozytorium:

codex mcp add esticrm -- \
  node \
  --env-file=/Users/jan/projekty/esticrm-mcp/.env \
  /Users/jan/projekty/esticrm-mcp/dist/index.js

Sprawdź konfigurację poleceniem codex mcp list. Sekrety pozostają w pliku .env i nie trafiają do historii poleceń.

W Windows PowerShell użyj znaku kontynuacji wiersza właściwego dla tej powłoki:

codex mcp add esticrm -- `
  node `
  --env-file=C:/Users/jan/projekty/esticrm-mcp/.env `
  C:/Users/jan/projekty/esticrm-mcp/dist/index.js

Połącz serwer z Claude

Claude Code odczytuje projektową konfigurację z pliku .mcp.json. Claude Desktop używa tego samego obiektu mcpServers w swoim pliku claude_desktop_config.json. Na macOS znajdziesz ten plik w ~/Library/Application Support/Claude/, a w Windows w %APPDATA%\Claude\.

{
  "mcpServers": {
    "esticrm": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--env-file=/Users/jan/projekty/esticrm-mcp/.env",
        "/Users/jan/projekty/esticrm-mcp/dist/index.js"
      ]
    }
  }
}

Zastąp przykładową nazwę jan i ścieżki pełną lokalizacją repozytorium. W Windows możesz użyć ścieżek z ukośnikami, na przykład C:/Users/jan/projekty/esticrm-mcp/.env. Uruchom ponownie aplikację Claude, a następnie sprawdź listę połączeń MCP. Projektowego pliku .mcp.json nie dodawaj do publicznego repozytorium, jeśli zawiera ustawienia właściwe dla Twojego środowiska.

Dostępne narzędzia MCP

Wersja 0.1 udostępnia polski interfejs do najczęstszych operacji. Dokładny wynik zależy od odpowiedzi API i uprawnień konta.

Narzędzie

Tryb

Zastosowanie

esticrm_lista_ofert

Odczyt

Pobiera stronicowaną listę ofert przez udokumentowane parametry skip i take

esticrm_szczegoly_oferty

Odczyt

Pobiera szczegóły jednej oferty

esticrm_dane_klienta

Odczyt

Pobiera klienta, domyślnie z ukrytymi danymi kontaktowymi

esticrm_oferty_klienta

Odczyt

Pobiera oferty powiązane z klientem

esticrm_lista_agentow

Odczyt

Pobiera listę agentów

esticrm_wyszukaj_lokalizacje

Odczyt

Wyszukuje lokalizacje obsługiwane przez EstiCRM

esticrm_pobierz_slownik

Odczyt

Pobiera obsługiwany słownik ofert, mapowania lub systemowy

esticrm_sprawdz_termin

Odczyt

Sprawdza dostępność terminu w kalendarzu

esticrm_wydarzenia_kalendarza

Odczyt

Pobiera wydarzenia z zadanego zakresu

esticrm_lista_inwestycji

Odczyt

Pobiera listę inwestycji

esticrm_lista_biur

Odczyt

Pobiera listę biur

esticrm_utworz_zapytanie

Zapis

Tworzy zapytanie klienta po włączeniu zapisów

esticrm_utworz_termin

Zapis

Tworzy termin po włączeniu zapisów

Klient MCP nie zobaczy dwóch narzędzi zapisu, dopóki ESTICRM_ENABLE_WRITES ma wartość false. Po zmianie ustawienia uruchom klienta ponownie i uważnie sprawdzaj argumenty każdego zapisu.

Narzędzia kalendarza przyjmują lokalny czas EstiCRM. Odczyt zakresu wymaga formatu RRRR-MM-DD GG:MM:SS, a utworzenie terminu — RRRR-MM-DD GG:MM. Publiczny kontrakt zapisu odpowiada bieżącym przykładom EstiCRM: zapytanie przekazuje między innymi e-mail agenta, transakcję, rynek i typ, natomiast termin może przekazać dane_klienta oraz numer_oferty. Pola zapisu nie są oznaczone w dokumentacji jako wymagane lub opcjonalne, dlatego przed użyciem produkcyjnym sprawdź je na własnym koncie testowym.

Ograniczenia API EstiCRM

Ten serwer służy do celowanych, interaktywnych operacji. Oficjalne materiały EstiCRM zalecają XML do pełnej lub masowej synchronizacji ofert z własną stroną. Nie używaj narzędzi MCP do cyklicznego pobierania całej bazy ani jako zamiennika eksportu XML.

Publiczna dokumentacja APIClient zawiera nieścisłości, w tym opisy wyglądające na skopiowane między operacjami. Projekt implementuje tylko jawnie obsługiwane wywołania i zabezpiecza ich kontrakty testami. Przed dodaniem kolejnej operacji potwierdź jej zachowanie na koncie testowym lub z pomocą EstiCRM.

W szczególności offer/list otrzymuje wyłącznie opublikowane parametry skip i take. Projekt celowo nie wysyła do tej operacji nieudokumentowanych filtrów status, type, transaction, phrase ani updateDate.

API może odpowiedzieć kodem HTTP 200 oraz result: false. Serwer sprawdza treść odpowiedzi, zamiast uznawać każdy kod 200 za sukces. Adres bazowy API jest celowo stały i nie można skierować tokenu na inny serwer przez zmienną środowiskową.

Chroń dane i zachowaj zgodność z RODO

Odpowiadasz za podstawę prawną, zakres i sposób przetwarzania danych pobranych z własnego konta. Ogólne rozporządzenie o ochronie danych (RODO) wymaga między innymi minimalizacji danych i ograniczenia dostępu.

Stosuj następujące zasady:

  • nadaj tokenowi najmniejszy dostęp potrzebny do zadania

  • pozostaw narzędzia zapisu wyłączone, jeśli ich nie używasz

  • nie wklejaj wyników zawierających dane osobowe do publicznych rozmów

  • sprawdź politykę przechowywania danych używanego klienta i modelu

  • regularnie zmieniaj token oraz unieważnij go po podejrzeniu ujawnienia

  • usuń parametry zapytań i dane klientów przed udostępnieniem logów

  • używaj fikcyjnych danych w testach, przykładach i zgłoszeniach

Serwer nie zapisuje tokenu w repozytorium i nie powinien umieszczać go w błędach. Sam klient MCP może jednak przekazać wynik narzędzia do wybranego modelu. Ogranicz zakres zapytania przed pobraniem danych.

Więcej zasad znajdziesz w dokumencie Zasady bezpieczeństwa.

Uruchom testy

Jedno polecenie sprawdza typy, testy, kompilację i połączenie MCP:

pnpm sprawdz

Możesz też uruchomić kontrole osobno:

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Testy muszą działać bez produkcyjnego konta EstiCRM. Nie dodawaj prawdziwych odpowiedzi API jako danych testowych.

Współtwórz projekt

Zgłoszenia błędów i propozycje są mile widziane. Przed zmianą kodu przeczytaj instrukcję współtworzenia, kodeks postępowania, zasady bezpieczeństwa i historię zmian.

Oficjalne źródła

Te materiały pomagają zweryfikować zachowanie integracji:

Licencja i znaki towarowe

Kod jest dostępny na warunkach licencji MIT. Nazwa EstiCRM oraz powiązane znaki należą do ich właścicieli i występują tu wyłącznie w celu opisania kompatybilności.

Available Tools

11 tools
esticrm_dane_klientaDane klienta EstiCRMA
Read-onlyIdempotent

Pobiera dane jednego klienta. Dane kontaktowe są domyślnie ukryte i pojawiają się tylko po jawnym ustawieniu parametru.

Inputs: id_klienta (required), pokaz_dane_kontaktowe. Returns: ok, blad, dane, opis, +1 more

esticrm_lista_agentowLista agentów EstiCRMA
Read-onlyIdempotent

Pobiera ograniczoną listę agentów bez ujawniania danych kontaktowych.

Inputs: limit. Returns: ok, blad, dane, opis, +1 more

esticrm_lista_biurLista biur EstiCRMA
Read-onlyIdempotent

Pobiera ograniczoną listę biur.

Inputs: limit. Returns: ok, blad, dane, opis, +1 more

esticrm_lista_inwestycjiLista inwestycji EstiCRMB
Read-onlyIdempotent

Pobiera lub filtruje ograniczoną listę inwestycji.

Inputs: fraza, limit. Returns: ok, blad, dane, opis, +1 more

esticrm_lista_ofertLista ofert EstiCRMB
Read-onlyIdempotent

Pobiera ograniczoną, stronicowaną listę ofert. Narzędzie jest tylko do odczytu.

Inputs: limit, strona. Returns: ok, blad, dane, opis, +1 more

esticrm_oferty_klientaOferty klienta EstiCRMA
Read-onlyIdempotent

Pobiera ograniczoną listę ofert przypisanych do jednego klienta.

Inputs: id_klienta (required), limit. Returns: ok, blad, dane, opis, +1 more

esticrm_pobierz_slownikSłownik EstiCRMA
Read-onlyIdempotent

Pobiera jeden z trzech słowników: ofert, mapowania ofert albo systemowy. Nie pozwala wywołać dowolnej ścieżki API.

Inputs: rodzaj (required), nazwa. Returns: ok, blad, dane, opis, +1 more

esticrm_sprawdz_terminSprawdzenie terminu EstiCRMA
Read-onlyIdempotent

Sprawdza dostępność terminu w kalendarzu wskazanym adresem e-mail agenta.

Inputs: do (required), od (required), kalendarz (required). Returns: ok, blad, dane, opis, +1 more

esticrm_szczegoly_ofertySzczegóły oferty EstiCRMA
Read-onlyIdempotent

Pobiera szczegóły jednej oferty po jej identyfikatorze.

Inputs: id_oferty (required). Returns: ok, blad, dane, opis, +1 more

esticrm_wydarzenia_kalendarzaWydarzenia kalendarza EstiCRMA
Read-onlyIdempotent

Pobiera ograniczoną listę wydarzeń z kalendarza wskazanego adresem e-mail agenta.

Inputs: do (required), od (required), kalendarz (required), limit. Returns: ok, blad, dane, opis, +1 more

esticrm_wyszukaj_lokalizacjeWyszukiwanie lokalizacji EstiCRMA
Read-onlyIdempotent

Wyszukuje lokalizacje po krótkiej frazie i ogranicza liczbę wyników.

Inputs: fraza (required), limit. Returns: ok, blad, dane, opis, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: offers, clients, agents, locations, dictionaries, calendar, investments, and offices. The overlapping offer-listing tools are clearly differentiated by scope (all offers vs. offers for a specific client), so an agent should not misselect.

    Naming Consistency4/5

    All tools share the esticrm_ prefix and use snake_case, with a mostly consistent action_noun pattern such as lista_ofert, pobierz_slownik, and sprawdz_termin. The pattern deviates slightly with noun-phrase names like szczegoly_oferty and wydarzenia_kalendarza.

    Tool Count5/5

    Eleven tools is a well-scoped set for a read-only CRM query server. Each tool covers a distinct data retrieval need without unnecessary duplication.

    Completeness4/5

    The surface covers offers, clients, agents, calendars, locations, investments, offices, and dictionaries, which is broad for a read-only toolset. The main gap is the absence of a client search or list endpoint to discover client IDs, though clients may be reachable through offer data.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      C
      maintenance
      Enables local MCP clients like Claude Code and Codex CLI to interact with RD Station CRM data, including contacts, organizations, deals, pipelines, and users.
      16
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables read-only access to wFirma accounting data—invoices, expenses, contractors, and declarations—through natural language in MCP clients like Claude or Codex.
      9
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude, ChatGPT and other MCP clients to read a financial adviser's CRM data—clients, households, reviews due, tasks, cases, plans and notes—and, when writes are enabled, create tasks and notes.
      14
      MIT