INSTALL-WINDOWS.md

INSTALL-WINDOWS.md

1. # Windows Install: Bitrix24 MCP Server
3. For a hands-on install on a staff member's Windows machine. Assumes Python
4. 3.10+ is installed (check: `py --version` in PowerShell; install from
5. python.org if missing, and check "Add python.exe to PATH" during setup).
7. > **This build performs writes** (lead/deal/contact/company) by default. To
8. > install a read-only copy, set `BITRIX_WRITES=off` in `.env`.
10. ## 1. Unzip
12. Unzip the package to a local, non-synced folder, e.g.:
14. ```
15. C:\Users\<username>\mcp-servers\bitrix-mcp
16. ```
18. **Not** OneDrive, Google Drive, or any synced folder: the `.env` secret and
19. logs must stay local.
21. ## 2. Run setup
23. Double-click `setup-windows.bat` (or run it from PowerShell). It creates the
24. venv, installs the pinned dependencies (including `tzdata`, required on
25. Windows for timezone support), and creates `.env` from the template.
27. ## 3. Webhook: created by the machine's owner, not copied
29. In **their own** Bitrix24 account (not yours): Developer resources → Other →
30. Inbound webhook. Scopes: **CRM, Users (user_brief), Tasks, Telephony, and
31. Open Channels + Messenger (imopenlines + im)**, nothing else. (Open
32. Channels/Messenger need a commercial plan; without them the chat tools just
33. report a missing scope.) Paste the URL into `.env` (Notepad is fine):
35. ```
36. BITRIX_WEBHOOK_URL=https://yourcompany.bitrix24.com/rest/NNNN/token/
37. BITRIX_LOCAL_TZ=America/Chicago
38. ```
40. Never copy a `.env` from another machine: the webhook must belong to the
41. person whose computer this is. That's what keeps permissions and audit
42. per-user.
44. ## 4. Smoke test
46. Double-click `smoke-test-windows.bat`. A startup line followed by silence
47. means it works. Close the window to stop. If it warns about timezones,
48. re-run `setup-windows.bat` (tzdata didn't install).
50. ## 5. Wire into Claude Desktop
52. Edit `%APPDATA%\Claude\claude_desktop_config.json` (Win+R →
53. `%APPDATA%\Claude` → open the file in Notepad). Note the **double
54. backslashes**, which JSON requires:
56. ```json
57. {
58. "mcpServers": {
59. "bitrix24": {
60. "command": "C:\\Users\\<username>\\mcp-servers\\bitrix-mcp\\.venv\\Scripts\\python.exe",
61. "args": ["C:\\Users\\<username>\\mcp-servers\\bitrix-mcp\\server.py"]
62. }
63. }
64. }
65. ```
67. Fully quit Claude Desktop (system tray → right-click → Quit, not just the X)
68. and reopen. The `bitrix24` tools (about 30) should appear.
70. ## 6. Verify
72. Ask Claude: *"How many leads are in the pipeline?"* It should return live
73. counts with stage names. Then confirm `logs\calls.jsonl` appeared inside the
74. install folder.
76. ## Security notes (Windows-specific)
78. - The `.env` file is protected by the Windows user account, so make sure the
79. machine's login is the owner's own and the screen locks automatically.
80. - BitLocker should be on (Settings → Privacy & security → Device encryption).
81. - Rotate the webhook token quarterly, rotate it immediately on any suspected
82. exposure, and tell whoever administers the Bitrix24 portal.