Skip to main content
Glama
README.md
# plando-mcp

[![ci](https://github.com/lieox/plando-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lieox/plando-mcp/actions/workflows/ci.yml)

שרת MCP שמחבר את Claude (Claude Code, Claude Desktop או כל לקוח MCP) למערכת **[Plando](https://plando.co.il)**: חיפוש לקוחות, רשימות לקוחות, היסטוריית CRM, חוגים ומפגשים, ובמצב כתיבה גם לידים, עדכון כרטיס, רשומות פעילות ונוכחות.

**לא רשמי.** הפרויקט לא קשור ל-Plando או ל-Tandemwise. הוא בנוי על [תיעוד ה-API הציבורי שלהם](https://plando.co.il/api-docs).

13 כלים. כברירת מחדל רק 9 כלי קריאה פעילים, כולל מערכת השעות (מה שבממשק של Plando נקרא "יומן"). 4 כלי הכתיבה נדלקים רק כשמוסיפים `PLANDO_ALLOW_WRITES=1`.

## מה צריך

- Node.js 18 ומעלה, ו-git (ההתקנה מושכת את השרת ישירות מהריפו הזה). ב-Windows, Claude Code כבר דורש Git for Windows, כך שבדרך כלל הוא מותקן.
- **מפתח הגישה של הארגון** ב-Plando: מנהל מערכת, הגדרות הארגון, `access_key`.

המפתח פותח את כל הארגון: כל אנשי הקשר, ההיסטוריה והמסמכים. לא מדביקים אותו בצ'אט, בצילום מסך, בווטסאפ או ב-git. אם Plando מאפשרים לכם מפתח נפרד עם הרשאות מצומצמות, עדיף לתת ל-Claude מפתח כזה. כדאי לשאול אותם.

### כתובת IP מורשית

חיפוש לקוחות, רשימות, היסטוריית CRM, חוגים ויומן ה-API עובדים רק מכתובת IP שרשומה בארגון ב-Plando. אם המחשב לא ברשימה, Claude יקבל הודעה ברורה שזו הבעיה.

הפתרון: לבקש מהתמיכה של Plando להוסיף לרשימת ה-IP המורשים של ה-API את כתובת ה-IP הציבורית של המחשב (או של המשרד). את הכתובת רואים בכניסה ל-https://api.ipify.org מהמחשב הזה. בבית ובמשרד הכתובת משתנה מדי פעם, ולפטופ ברשת אחרת מקבל כתובת אחרת, אז ייתכן שיהיה צריך לעדכן אותה שוב בהמשך.

**לא לבקש `all_ips`**. מפתח הגישה מופיע לפעמים בקוד של טופס לידים באתר, ו-`all_ips` מאפשר לכל מי שמחזיק בו לקרוא את כל אנשי הקשר מכל מקום.

## התקנה ב-Claude Code

### Windows

שתי שורות, ב-**Command Prompt** (מחפשים `cmd` בתפריט התחל), לא ב-PowerShell:

```
npm install -g github:lieox/plando-mcp
claude mcp add -e PLANDO_ACCESS_KEY=your-access-key -s user plando cmd /c plando-mcp
cls
```

- **`cls` בסוף** מנקה את המסך, כדי שהמפתח לא יישאר עליו ולא ייכנס בטעות לצילום מסך.
- **Command Prompt ולא PowerShell:** בהרבה מחשבים PowerShell חוסם את `npm` עצמו (`running scripts is disabled on this system`).
- **התקנה פעם אחת ולא דרך npx:** כך השרת עולה מיד, ו-Claude Code לא מוותר עליו בהפעלה הראשונה.
- **`-s user` צמוד לפני השם**, אחרי כל ה-`-e`.

לעדכון גרסה מריצים שוב את שורת ה-`npm install -g`.

### macOS

שורה אחת:

```bash
claude mcp add plando -s user -e PLANDO_ACCESS_KEY=your-access-key -- npx -y github:lieox/plando-mcp
```

### ואז, בשניהם

מפעילים מחדש את Claude Code, מריצים `/mcp` ובודקים ש-`plando` מחובר. אחר כך שואלים, למשל: *"תמצא בפלנדו את הלקוח עם הטלפון 050-1234567"*.

**לא להריץ `claude mcp get plando`**, ולא לבקש מ-Claude להריץ אותה. הפקודה מדפיסה את המפתח בגלוי. לבדיקת חיבור משתמשים ב-`/mcp`.

### להפעיל כתיבה

אחרי שהקריאה עובדת, מסירים ומוסיפים מחדש עם `-e PLANDO_ALLOW_WRITES=1`:

```
claude mcp remove plando -s user
claude mcp add -e PLANDO_ACCESS_KEY=your-access-key -e PLANDO_ALLOW_WRITES=1 -s user plando cmd /c plando-mcp
cls
```

(ב-macOS: אותה שורת `npx` עם `-e PLANDO_ALLOW_WRITES=1`.)

**לפני שמפעילים כתיבה:** שינוי סטטוס של לקוח, רישום פעילות מסוג מסוים או ליד חדש יכולים להפעיל את התהליכים האוטומטיים שהוגדרו ב-Plando, כולל SMS או וואטסאפ ללקוח. Claude מתבקש לפרט מה ישתנה ולחכות לאישור לפני כל כתיבה. לא מאשרים אוטומטית את כלי הכתיבה של השרת הזה.

## Claude Desktop

לא נבדק ב-CI. Settings, Developer, Edit Config, ומוסיפים:

```json
{
  "mcpServers": {
    "plando": {
      "command": "npx",
      "args": ["-y", "github:lieox/plando-mcp"],
      "env": { "PLANDO_ACCESS_KEY": "your-access-key" }
    }
  }
}
```

סוגרים את Claude Desktop לגמרי ופותחים מחדש.

## כלים

| תחום | קריאה (תמיד פעיל) | כתיבה (רק עם `PLANDO_ALLOW_WRITES=1`) |
|---|---|---|
| לקוחות | `find_contact`, `list_contacts`, `lookup_phone` | `create_lead`, `update_contact` |
| CRM | `get_crm_records` | `add_crm_record` (כולל משימת המשך) |
| חוגים ויומן | `get_schedule`, `get_contact_groups`, `get_group_events` | `record_attendance` |
| בקרה | `get_api_log`, `usage` | |

כל שם כלי מתחיל ב-`plando_`.

דוגמאות למה לבקש:

- *"מי הלקוחות שנוספו החודש?"*
- *"מה ההיסטוריה של דנה כהן, 050-1234567?"* (עם טלפון או מייל, כי אין חיפוש לפי שם בלבד)
- *"מה מערכת השעות של השבוע הבא?"*
- *"באילו חוגים רשום הלקוח 4996255, ומתי המפגש הבא?"*
- *"הליד מהטופס באתר מאתמול בצהריים הגיע לפלנדו?"*
- במצב כתיבה: *"תרשום לדנה שיחת היכרות ומשימה לחזור אליה ביום ראשון"*

## הגדרות

| משתנה | משמעות |
|---|---|
| `PLANDO_ACCESS_KEY` | חובה. מפתח הגישה של הארגון. |
| `PLANDO_ALLOW_WRITES` | `1` מוסיף את 4 כלי הכתיבה. בלעדיו Claude לא יכול לשנות כלום ב-Plando. |
| `PLANDO_SHOW_SENSITIVE` | `1` מציג גם רשומות CRM שסומנו רגישות ב-Plando. כברירת מחדל הן מוסתרות, ו-Claude רק רואה כמה הוסתרו. |
| `PLANDO_MONTHLY_QUOTA` | מכסת הקריאות החודשית במסלול שלכם (ברירת מחדל 2000). מעל 80% Claude מקבל אזהרה. |
| `PLANDO_GROUP_IDS` | מספרי הקבוצות שמערכת השעות מכסה, מופרדים בפסיק, למשל `109342,109350`. לא חובה (ראו "מערכת השעות"). |

## מערכת השעות (יומן)

`get_schedule` מחזיר את כל השיעורים בטווח של עד 31 יום, מכל הקבוצות, לפי סדר הזמנים, עם שם הקבוצה.

ל-API של Plando אין קריאה שמחזירה את רשימת כל הקבוצות, אז השרת צריך לדעת את מספרי הקבוצות. יש שתי דרכים:

- **בלי הגדרה:** Claude מוצא את הקבוצה כשהוא בודק תלמיד שרשום אליה, וזוכר אותה עד סוף השיחה.
- **קבוע:** שומרים את המספרים ב-`PLANDO_GROUP_IDS`, ומערכת השעות עובדת מההתחלה בכל שיחה. אחרי שבודקים תלמיד אחד מכל קבוצה, אפשר לבקש מ-Claude את רשימת המספרים. אחר כך מסירים ומוסיפים מחדש את השרת, כמו ב"להפעיל כתיבה", עם עוד `-e PLANDO_GROUP_IDS=109342,109350`. את זה עושים בעצמכם ולא דרך Claude, כי בפקודה יש את המפתח.

כל קבוצה היא קריאת API אחת מהמכסה, אז מערכת שעות של 20 קבוצות עולה 20 קריאות.

**שינויים במערכת השעות לא אפשריים דרך ה-API של Plando:** אין בו יצירה, הזזה או ביטול של שיעור. עושים את זה במסך של Plando (פעילויות, רשימת פעילויות).

## מה חשוב לדעת

- **מכסת קריאות:** ב-Plando יש 2,000 קריאות API בחודש במסלול בסיסי, 5,000 במקצועי ו-10,000 בעסקי, והטפסים באתר משתמשים באותה מכסה. כל שימוש בכלי הוא קריאה אחת, ורשימת לקוחות מחזירה עד 50 בכל קריאה. שאלה על טלפון, מייל או לקוח מסוים עולה קריאה אחת. שאלה על "כולם" יכולה לעלות עשרות. השרת סופר את הקריאות שיצאו מהמחשב הזה (`plando_usage`), אבל לא רואה קריאות ממקומות אחרים.
- **אין חיפוש לפי שם.** ה-API מחפש לפי טלפון, מייל, ת"ז או מספר לקוח. שם לבד לא מספיק.
- **טלפון משותף:** הרבה פעמים כמה אנשי קשר רשומים עם אותו טלפון, למשל אחים עם הנייד של ההורה. `lookup_phone` מחזיר רק את הראשון, ו-Claude מתבקש לוודא מי האדם לפני שהוא פועל.
- **מה אין ב-API של Plando:** רשימת חשבוניות ומסמכים, רשימת משימות, רשימת כל הקבוצות, שליחה ישירה של SMS, מייל או וואטסאפ, ומחיקת אנשי קשר. השרת לא יכול לעשות את מה שה-API לא מאפשר. אבל כתיבה יכולה להפעיל אוטומציה של Plando ששולחת הודעה (ראו "להפעיל כתיבה").
- **כסף לא בגרסה הזו:** ה-API של Plando יודע להפיק חשבוניות ולחייב כרטיס או הוראת קבע. השרת הזה בכוונה לא כולל את זה.
- **המידע מגיע גם מהציבור:** שדות של אנשי קשר, טקסט ברשומות ויומן ה-API מכילים מה שאנשים הקלידו בטפסים באתר. Claude מתבקש להתייחס לזה כמידע בלבד ולא כהוראות. בשיחות שמשתמשות בשרת הזה לא כדאי לאשר אוטומטית כלים כמו Bash או WebFetch.
- **פרטיות:** מה ש-Claude קורא מ-Plando עובר למודל. העסק הוא האחראי על המאגר, ולכן כדאי להפעיל את זה רק על מה שבאמת צריך, ולהשאיר רשומות רגישות מוסתרות.
- **כפילויות ודריסה:** בדרך כלל ליד חדש יוצר איש קשר חדש. אבל עם `update_if_exists`, או כש-Plando מוגדר בארגון לעדכן קיימים, הוא מחפש איש קשר תואם (לפי מייל או טלפון ושם) ומעדכן אותו. לכן לא משתמשים במייל של ההורה עבור ילד נוסף בלי לבדוק קודם.
- **עדכון לקוח מחליף את הערך הקיים.** כדי להוסיף הערה משתמשים ב-`add_crm_record`, לא בעדכון של `remark`. שם שדה לא מוכר נדחה לפני שליחה.

## פיתוח

```bash
npm install
npm run compile    # src/ ל-dist/
npm test           # בדיקה מול שרת דמה מקומי, ובדיקה אחת מול plando.co.il עם מפתח מזויף
npm run dev        # מצב צפייה
```

`dist/` נשמר בריפו בכוונה, כדי שהתקנה מגיטהאב לא תצטרך שלב בנייה. אחרי כל שינוי ב-`src/` מקמפלים ושומרים גם אותו (ה-CI נכשל אם הם לא תואמים). סקריפט הקומפילציה בכוונה לא נקרא `build`, כי npm מתקין אז את כלי הפיתוח אצל כל משתמש וההפעלה הראשונה ב-Windows נהיית איטית מדי.

`test/mock-plando.mjs` מדמה את Plando לפי התיעוד, כולל ההתנהגויות הלא שגרתיות: HTTP 200 עם קוד שגיאה בגוף, `contacts` כמחרוזת JSON בתוך JSON, ותשובות טקסט של מספר בודד.

## English

Unofficial MCP server for the [Plando](https://plando.co.il) CRM API (Israel). 9 read tools (find and list contacts, reverse phone lookup, CRM activity history, a class timetable across groups, course groups and events, API log, local usage counter) and 4 write tools that are registered only with `PLANDO_ALLOW_WRITES=1` (create lead, update contact, add CRM record or follow-up task, record attendance). Invoicing and card charging are deliberately left out. Records marked sensitive are hidden unless `PLANDO_SHOW_SENSITIVE=1`. The access key never appears in tool output.

Plando enforces an IP allowlist on most read endpoints and a monthly API quota per plan. Writes can trigger the organization's Plando automations (including SMS or WhatsApp to the contact), so the server tells Claude to confirm every write with the user. Data returned by the tools can contain text typed by the public; the server tells Claude to treat it as data, not instructions. Do not run `claude mcp get plando`: it prints the key. Install commands are above (Windows: Command Prompt; macOS: one `npx` line).

## License

MIT