mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/meridian-crm-mcpmainPrivate on GitHub, published here in full

README.md

Markdown8.4 KB172 lines

README.md

  1. # Bitrix24 MCP Server
  3. A local MCP server that lets Claude Desktop **read and write** a company's
  4. Bitrix24 CRM, tasks, telephony, and website chats over an inbound webhook.
  6. **The company is fictional.** This server was built for, and used every day at,
  7. a real print and display shop. Here it serves **Meridian Display Co.**, the
  8. invented company behind
  9. [meridian-ops-board](https://github.com/mattrguerra/meridian-ops-board): this
  10. is the CRM side of the same system. Funnel names, field labels and examples are
  11. Meridian's; the engineering is the real server's.
  13. > **This server performs writes.** Lead writes, funnel-locked deal writes
  14. > (including `create_deal`), and contact/company create/update are **enabled by
  15. > default**. Set `BITRIX_WRITES=off` for a fully read-only server.
  17. ## Deployment model
  19. Local, per-machine, stdio: Claude Desktop launches `server.py` as a subprocess
  20. on each staff member's machine. There is **no network listener**, so the
  21. security boundary is the **webhook secret** in `.env` and the scopes you grant
  22. it. See "Security & opsec" below before distributing.
  24. ## What it does
  26. 30 tools. Reads are unrestricted; writes are gated by `BITRIX_WRITES` (and deal
  27. writes are additionally locked to specific funnels).
  29. ### Reads
  30. | Tool | Purpose |
  31. | ---- | ------- |
  32. | `search_crm` | Find leads/contacts/companies/deals by name, email, or phone |
  33. | `get_record` | Full detail on a record, incl. custom fields + an order summary |
  34. | `get_timeline` | Activity history (calls, emails, comments) + website chats |
  35. | `get_chat_transcript` | Website live-chat (Open Channel) conversations on a record |
  36. | `list_tasks` | Your open/overdue/completed tasks |
  37. | `pipeline_summary` | Exact per-stage counts (batched), with stage names |
  38. | `list_records` | List records by assignee, stage, field, funnel, or date |
  39. | `get_fields` / `find_field` | Field schema / search fields by label across entities |
  40. | `get_products` | Line items on a record (product, qty, price, total) |
  41. | `get_stage_history` | Stage movement with time-in-stage |
  42. | `get_call_history` | Recent telephony calls (with CALL_IDs and recording flags) |
  43. | `get_call_recording` | Recording URL/file + bound record for one call |
  44. | `list_pipelines` | Deal funnels (with stages) + smart processes |
  46. ### Writes (gated by `BITRIX_WRITES`)
  47. | Tool | Scope of write |
  48. | ---- | -------------- |
  49. | `add_lead_comment`, `rename_lead`, `set_lead_fields` | Leads |
  50. | `add_deal_comment`, `set_deal_title`, `set_deal_stage`, `set_deal_fields`, `assign_deal`, `link_deal_contact`, `link_deal_company`, `create_deal` | Deals, **write-enabled funnels only** |
  51. | `create_contact`, `update_contact`, `create_company`, `update_company` | Parties, gated also by `BITRIX_WRITE_PARTIES`; create dup-checks first |
  52. | `transcribe_call` | Local transcription, opt-in via `BITRIX_TRANSCRIBE` |
  54. `set_lead_fields` / `set_deal_fields` take a `{label: value}` object and
  55. translate enum options, yes/no booleans, and dates automatically, e.g.
  56. `{"Follow-up Status": "Quote Sent", "Rush Job": "yes"}`.
  58. ## Webhook permissions (required)
  60. Create one **Inbound webhook** (Applications → Developer resources → Other →
  61. Inbound webhook) and enable exactly these scopes:
  63. | Scope | Powers |
  64. | ----- | ------ |
  65. | `crm` | all CRM reads + writes |
  66. | `user_brief` | assignee / author names (upgrade to `user` if names look thin) |
  67. | `task` | `list_tasks` |
  68. | `telephony` | `get_call_history`, `get_call_recording`, transcription |
  69. | `imopenlines` + `im` | website-chat read (commercial plan required) |
  71. Without `imopenlines`/`im`, chat tools degrade gracefully (timeline still works).
  72. Without `telephony`, the call tools return a clear "missing scope" message.
  74. > **CoPilot note.** Bitrix CoPilot's generated transcripts/summaries are **not**
  75. > readable over REST, and a call's `TRANSCRIPT_ID` has no getter. "CoPilot-style"
  76. > value here comes from **Claude** summarizing the data these tools expose
  77. > (chat transcripts, recordings, timeline), not from reading CoPilot itself.
  79. ## Security & opsec (read before distributing)
  81. - **The webhook URL is a password.** Anyone with it has the webhook user's full
  82. API access from anywhere (Bitrix cloud webhooks can't be IP-restricted).
  83. - Choose a webhook-owner model and stick to it:
  84. - **Per-user** (what the Windows install uses): each person's webhook lives in
  85. *their own* Bitrix account, so actions are attributable to them. Never copy
  86. one person's `.env` to another machine.
  87. - **Dedicated service user**: one non-admin "CRM Automation" account scoped to
  88. only what's needed: simplest least-privilege, but loses per-user audit.
  89. - Enable **2FA** on whichever account owns the webhook.
  90. - `chmod 600 .env` on every machine. Never commit `.env` (it's gitignored).
  91. - Have a **rotation plan**: if a machine is lost, delete + recreate the webhook
  92. in Bitrix and update `.env`.
  93. - **Token never logged.** httpx request logging is silenced and all error paths
  94. redact the webhook URL.
  95. - **Logs are PII-scrubbed by default.** `logs/calls.jsonl` records tool calls
  96. for migration analysis; `BITRIX_LOG_ARGS=redact` (default) masks emails/phones
  97. and blanks customer names/free text. Use `full` only on a trusted solo machine;
  98. `off` to log no arguments. The log self-rotates past `BITRIX_LOG_MAX_BYTES`.
  99. - **Untrusted content is fenced.** Customer/visitor free text (record fields,
  100. email/chat bodies) is wrapped as untrusted data so the model treats it as data,
  101. never instructions. Keep per-write confirmation on in Claude Desktop.
  103. ## Setup
  105. ```bash
  106. cd meridian-crm-mcp
  107. python3 -m venv .venv
  108. source .venv/bin/activate # Windows: .venv\Scripts\activate
  109. pip install -r requirements.txt
  111. cp .env.example .env
  112. # paste your webhook URL and adjust settings
  113. chmod 600 .env # macOS/Linux
  114. ```
  116. Smoke test: `python server.py` should log a startup line and wait silently.
  117. Ctrl+C to stop. Then wire it into Claude Desktop's `claude_desktop_config.json`
  118. under `mcpServers` with absolute paths to the venv python and `server.py`, and
  119. restart Claude Desktop.
  121. ## Checks
  123. ```bash
  124. pip install -r requirements.txt pytest ruff
  125. ruff check .
  126. python -m py_compile server.py
  127. pytest
  128. BITRIX_WEBHOOK_URL=https://example.invalid/rest/1/x BITRIX_DATA_DIR=$(mktemp -d) \
  129. python server.py # starts on stdio; Ctrl+C to stop
  130. cd mcpb && ./build.sh # mcpb validate + pack
  131. ```
  133. The tests need no webhook and make no network calls: `tests/conftest.py` sets
  134. the environment before importing `server.py` and swaps `bitrix_call` for a
  135. recording fake, and `bitrix_call` itself runs against `httpx.MockTransport`.
  136. `tests/tool_api.json` records the 30 tools' names, docstrings and parameter
  137. schemas, so any change to what the model sees fails the suite until the
  138. contract file is updated on purpose. CI runs lint, compile and tests on
  139. Python 3.10 and 3.12.
  141. ## Configuration
  143. All settings live in `.env` (see `.env.example` for the annotated list):
  144. `BITRIX_WEBHOOK_URL`, `BITRIX_LOCAL_TZ`, `BITRIX_WRITES`, `BITRIX_WRITE_FUNNELS`,
  145. `BITRIX_WRITE_PARTIES`, `BITRIX_LOG_ARGS`, `BITRIX_LOG_MAX_BYTES`,
  146. `BITRIX_TRANSCRIBE`.
  148. ## Architecture notes
  150. - **Universal API.** Reads use the `crm.item.*` family (entityTypeId: lead 1,
  151. deal 2, contact 3, company 4). The one exception is **party create/update**,
  152. which uses legacy `crm.contact.*` / `crm.company.*` because `crm.item.add`
  153. silently drops phone/email multifields.
  154. - **Batched counts.** `pipeline_summary` runs all per-stage counts in one
  155. `rest.batch` round-trip (chunked at 50). One shared `httpx.AsyncClient` pools
  156. connections across calls.
  157. - **Semantic tool names** (`search_crm`, not `bitrix_crm_search`) so the
  158. interface survives a future CRM migration; only the implementation swaps.
  159. - **Schema drift tracking.** Field schemas snapshot to `./schema/` (one dated
  160. file per entity per day) so form-builder changes are diffable over time.
  161. The snapshots are gitignored: they hold the live CRM's own field definitions.
  163. ## Troubleshooting
  165. - **`BITRIX_WEBHOOK_URL not set`**: `.env` missing/empty.
  166. - **`insufficient_scope`**: add the missing scope to the webhook (see table).
  167. - **Chat tools say insufficient_scope**: add `imopenlines` + `im` (commercial
  168. plan required).
  169. - **A deal write is "Refused… not a write-enabled funnel"**: the deal isn't in
  170. `BITRIX_WRITE_FUNNELS`; that's the funnel lock working as intended.
  171. - **Custom field shows as `UF_CRM_…`**: it's a custom field; `get_record` shows
  172. its label, and `get_fields` / `find_field` dump the schema.