{"_id":"@alexbuzo/outlook-mcp","name":"@alexbuzo/outlook-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alexbuzo/outlook-mcp","version":"0.1.0","description":"Outlook/Exchange EWS MCP server exposing mailbox tools over stdio.","license":"MIT","author":{"name":"Aliaksei Buzo aliakseibuzo@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/abuzo/outlook-mcp.git"},"bugs":{"url":"https://github.com/abuzo/outlook-mcp/issues"},"homepage":"https://github.com/abuzo/outlook-mcp#readme","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"keywords":["mcp","model-context-protocol","outlook","exchange","ews","ntlm","email"],"engines":{"node":">=20"},"bin":{"outlook-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","test":"vitest run","lint":"eslint .","format":"prettier --write .","prepack":"npm run build","prepublishOnly":"npm run build && npm test && npm run lint","ews:ping":"tsx src/scripts/ewsPing.ts","ews:find-inbox":"tsx src/scripts/ewsFindInbox.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","dotenv":"^17.2.3","fast-xml-parser":"^5.7.2","html-to-text":"^9.0.5","node-libcurl":"^5.0.2","pino":"^10.1.0","zod":"^3.25.76"},"devDependencies":{"@eslint/js":"^9.39.1","@types/html-to-text":"^9.0.4","@types/node":"^20.19.24","eslint":"^9.39.1","prettier":"^3.6.2","tsx":"^4.20.6","typescript":"^5.9.3","typescript-eslint":"^8.46.3","vitest":"^4.0.3"},"_id":"@alexbuzo/outlook-mcp@0.1.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-wCVF/fm7xyau9OgaNeuvSlmZQu5uSRZB7l8nVhMgmPT59DroSgB005ixT7Yx+D9kuk6ABHyP42rfC7lrbp1t2A==","shasum":"6abb97e4daadc167cad144b9aba722813b41d8ef","tarball":"https://registry.npmjs.org/@alexbuzo/outlook-mcp/-/outlook-mcp-0.1.0.tgz","fileCount":151,"unpackedSize":189184,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGVB0DoRsvGL0pBCjXwvEUZgelmpqD/uGYKFBHjp9MdwAiEAvGpYvBGx3TthrIGGxavkrefVCwUgmfgnK1vyZBYQLSY="}]},"_npmUser":{"name":"alexbuzo","email":"aliakseibuzo@gmail.com"},"directories":{},"maintainers":[{"name":"alexbuzo","email":"aliakseibuzo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/outlook-mcp_0.1.0_1777117630248_0.7113623285616952"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T11:47:10.146Z","0.1.0":"2026-04-25T11:47:10.453Z","modified":"2026-04-25T11:47:10.702Z"},"maintainers":[{"name":"alexbuzo","email":"aliakseibuzo@gmail.com"}],"description":"Outlook/Exchange EWS MCP server exposing mailbox tools over stdio.","homepage":"https://github.com/abuzo/outlook-mcp#readme","keywords":["mcp","model-context-protocol","outlook","exchange","ews","ntlm","email"],"repository":{"type":"git","url":"git+https://github.com/abuzo/outlook-mcp.git"},"author":{"name":"Aliaksei Buzo aliakseibuzo@gmail.com"},"bugs":{"url":"https://github.com/abuzo/outlook-mcp/issues"},"license":"MIT","readme":"# outlook-mcp\n\nЛокальный MCP-сервер для работы с Outlook / Exchange mailbox через EWS SOAP API, NTLM, HTTP/1.1 и persistent keep-alive connection.\n\nСервер не вызывает LLM сам. Он предоставляет MCP tools и возвращает структурированные JSON-данные. Анализ, суммаризация и reasoning выполняются внешним MCP-клиентом: Cursor, Cline, Claude Desktop или другим совместимым клиентом.\n\n## Архитектура\n\n```text\nMCP client\n  ↓ stdio\noutlook-mcp\n  ↓ EWS SOAP + NTLM + HTTP/1.1\nExchange EWS\n  ↓\nExchange mailbox\n```\n\nTools зависят от `MailService`, а не от EWS напрямую. Сейчас реализован `EwsMailService`; позже можно добавить `GraphMailService` без переписывания MCP tools.\n\n## Когда использовать EWS\n\nЭтот сервер полезен для Exchange environments, где доступен EWS endpoint, но Microsoft Graph недоступен или не подходит: on-prem Exchange, hybrid deployments, legacy enterprise setups или environments с NTLM/Negotiate authentication.\n\nBasic Auth не используется. Основной backend — EWS SOAP через NTLM over HTTP/1.1. Архитектура оставляет место для Graph backend позже.\n\n## Требования\n\n- Node.js 20+\n- Доступ к VPN или внутренней сети, если EWS endpoint не публичный\n- Доступ к EWS URL\n- Доменный пользователь\n- NTLM-аутентификация\n\n## Ручная проверка EWS\n\nПроверить endpoint:\n\n```bash\ncurl -I https://mail.example.com/EWS/Exchange.asmx\n```\n\nОжидаемо:\n\n```text\n401 Unauthorized\nWWW-Authenticate: NTLM\nWWW-Authenticate: Negotiate\n```\n\nПроверить NTLM:\n\n```bash\ncurl -v --http1.1 --ntlm -u 'DOMAIN\\\\username' https://mail.example.com/EWS/Exchange.asmx\n```\n\nОжидаемо:\n\n```text\nHTTP/1.1 200 OK\nPersistent-Auth: true\n```\n\n## Установка из npm\n\nПосле публикации пакет можно запускать через `npx`:\n\n```bash\nnpx -y @alexbuzo/outlook-mcp\n```\n\nИли установить глобально:\n\n```bash\nnpm install -g @alexbuzo/outlook-mcp\noutlook-mcp\n```\n\n## Локальная разработка\n\n```bash\ngit clone https://github.com/abuzo/outlook-mcp.git\ncd outlook-mcp\nnpm install\nnpm run build\nnpm test\n```\n\n## Настройка env\n\nСкопируйте `.env.example` в `.env` и заполните:\n\n```env\nMAIL_BACKEND=ews\nEWS_URL=https://mail.example.com/EWS/Exchange.asmx\nEWS_AUTH_TYPE=ntlm\nEWS_DOMAIN=EXAMPLE\nEWS_USERNAME=<domain-user>\nEWS_PASSWORD=<ews-password>\nMAILBOX_SMTP=user@example.com\n```\n\nКлючевые политики по умолчанию:\n\n```env\nALLOW_SEND=false\nALLOW_MOVE=false\nALLOW_MARK_READ=true\nALLOWED_SEND_DOMAINS=example.com\n```\n\nЕсли `ALLOWED_SEND_DOMAINS` пустой, отправка считается allow all только при `ALLOW_SEND=true`. Это рискованный режим; используйте его только осознанно.\n\n## Проверка EWS\n\n```bash\nnpm run ews:ping\nnpm run ews:find-inbox\n```\n\n## Запуск локально\n\n```bash\nnpm run dev\n```\n\n`npm run dev` запускает MCP server на stdio. В MCP runtime stdout используется только для JSON-RPC протокола, все логи идут в stderr.\n\n## MCP config\n\nПример для Cursor/Cline/Claude Desktop при запуске опубликованного npm-пакета:\n\n```json\n{\n  \"mcpServers\": {\n    \"outlook-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alexbuzo/outlook-mcp\"],\n      \"env\": {\n        \"MAIL_BACKEND\": \"ews\",\n        \"EWS_URL\": \"https://mail.example.com/EWS/Exchange.asmx\",\n        \"EWS_AUTH_TYPE\": \"ntlm\",\n        \"EWS_DOMAIN\": \"EXAMPLE\",\n        \"EWS_USERNAME\": \"<domain-user>\",\n        \"EWS_PASSWORD\": \"<ews-password>\",\n        \"MAILBOX_SMTP\": \"user@example.com\",\n        \"ALLOW_SEND\": \"false\",\n        \"ALLOW_MOVE\": \"false\",\n        \"ALLOW_MARK_READ\": \"true\",\n        \"ALLOWED_SEND_DOMAINS\": \"example.com\"\n      }\n    }\n  }\n}\n```\n\nПример для локального checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"outlook-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/outlook-mcp/dist/index.js\"],\n      \"env\": {\n        \"MAIL_BACKEND\": \"ews\",\n        \"EWS_URL\": \"https://mail.example.com/EWS/Exchange.asmx\",\n        \"EWS_AUTH_TYPE\": \"ntlm\",\n        \"EWS_DOMAIN\": \"EXAMPLE\",\n        \"EWS_USERNAME\": \"<domain-user>\",\n        \"EWS_PASSWORD\": \"<ews-password>\",\n        \"MAILBOX_SMTP\": \"user@example.com\",\n        \"ALLOW_SEND\": \"false\",\n        \"ALLOW_MOVE\": \"false\",\n        \"ALLOW_MARK_READ\": \"true\",\n        \"ALLOWED_SEND_DOMAINS\": \"example.com\"\n      }\n    }\n  }\n}\n```\n\n## MCP tools\n\n- `search_emails` — поиск писем без full body.\n- `read_email` — чтение metadata и опционально body с ограничением размера.\n- `read_thread` — чтение цепочки по `conversationId`.\n- `list_attachments` — metadata вложений без скачивания binary content.\n- `extract_action_items` — deterministic helper по простым русским и английским маркерам.\n- `create_draft` — создание черновика, без отправки.\n- `create_reply_draft` — создание reply/reply-all черновика, без отправки.\n- `send_draft` — отправка только существующего draft при `ALLOW_SEND=true` и `confirm=true`.\n- `mark_as_read` — установка read/unread при `ALLOW_MARK_READ=true`.\n- `move_email` — перемещение в `inbox`, `archive` или `deleteditems` при `ALLOW_MOVE=true`.\n\n## Security notes\n\n- Read-only by default: отправка и перемещение выключены.\n- `send_draft` требует `ALLOW_SEND=true` и `confirm=true`.\n- Permanent delete не реализован.\n- Binary content вложений не скачивается.\n- Пароль, NTLM challenge/response, Authorization headers, body писем и вложения не логируются.\n- Audit log пишет timestamp, tool, action type, target id, success/failure и sanitized error.\n- Body ограничивается `MAX_BODY_CHARS`.\n- Количество результатов ограничивается `MAX_SEARCH_RESULTS` и `MAX_THREAD_MESSAGES`.\n- Отправка проверяет recipients по `ALLOWED_SEND_DOMAINS`.\n- TLS verification не отключается.\n\n## Troubleshooting\n\n### HTTP_1_1_REQUIRED\n\nПричина: Exchange не принимает NTLM over HTTP/2. Решение: `EWS_FORCE_HTTP1=true`.\n\n### 401 Unauthorized\n\nВозможные причины:\n\n- неверный `EWS_DOMAIN`;\n- неверный `EWS_USERNAME` или `EWS_PASSWORD`;\n- EWS недоступен для пользователя;\n- VPN не подключен.\n\n### 403 Forbidden\n\nВозможные причины:\n\n- политика Exchange запрещает EWS;\n- mailbox недоступен для пользователя.\n\n### SELF_SIGNED_CERT / certificate issue\n\nНе отключайте TLS verification без согласования. Проверьте корпоративный root CA в системном trust store.\n\n### MCP protocol broken\n\nПричина: что-то пишет в stdout. В MCP runtime stdout должен содержать только JSON-RPC. Все logs, debug и startup errors должны идти в stderr.\n\n### node-libcurl install problems\n\nНа macOS обычно достаточно:\n\n```bash\nnpm install\n```\n\nЕсли сборка native dependency не проходит:\n\n```bash\nxcode-select --install\nbrew install curl\nnpm install\n```\n\n## Ограничения MVP\n\n- Нет скачивания вложений.\n- Нет Microsoft Graph backend.\n- Нет OAuth backend.\n- Нет Kerberos/Negotiate backend.\n- Нет shared mailbox impersonation.\n- Нет UI.\n- Нет автоматической отправки писем.\n- Нет permanent delete.\n\n## Roadmap\n\n- Graph backend.\n- OAuth EWS backend.\n- Kerberos/Negotiate backend.\n- Shared mailbox support.\n- Attachment download with policy.\n- Secure password storage через macOS Keychain.\n- Docker packaging.\n","readmeFilename":"README.md","_rev":"1-852daf1cfd1101341332f682dbca3606"}