{
  "markdown": "<!-- studiomeyer-mcp-stack-banner:start -->\n> **Part of the [StudioMeyer MCP Stack](https://studiomeyer.io)** — Built in Mallorca 🌴 · ⭐ if you use it\n<!-- studiomeyer-mcp-stack-banner:end -->\n\n<div align=\"center\">\n\n# mcp-personal-suite\n\n\n<!-- badges -->\n[![npm version](https://img.shields.io/npm/v/mcp-personal-suite?style=flat-square&color=cb3837&logo=npm&label=npm)](https://www.npmjs.com/package/mcp-personal-suite)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-personal-suite?style=flat-square&color=cb3837&logo=npm&label=installs%2Fmo)](https://www.npmjs.com/package/mcp-personal-suite)\n![License](https://img.shields.io/github/license/studiomeyer-io/mcp-personal-suite?style=flat-square&color=22c55e&label=license)\n![Last commit](https://img.shields.io/github/last-commit/studiomeyer-io/mcp-personal-suite?style=flat-square&color=88c0d0&label=updated)\n![GitHub stars](https://img.shields.io/github/stars/studiomeyer-io/mcp-personal-suite?style=flat-square&color=ffd700&logo=github&label=stars)\n<!-- /badges -->**Local-first personal productivity MCP server. 49 tools. BYOK. No cloud. No signup.**\n\nEmail, Calendar, Messaging, Search, Image Generation — all in one MCP server,\nrunning entirely on your machine. Works with Claude Desktop, Claude Code, Cursor,\nand any MCP client.\n\n[![npm](https://img.shields.io/npm/v/mcp-personal-suite)](https://www.npmjs.com/package/mcp-personal-suite)\n[![downloads](https://img.shields.io/npm/dm/mcp-personal-suite)](https://www.npmjs.com/package/mcp-personal-suite)\n[![license](https://img.shields.io/npm/l/mcp-personal-suite)](./LICENSE)\n[![node](https://img.shields.io/node/v/mcp-personal-suite)](./package.json)\n[![CI](https://github.com/studiomeyer-io/mcp-personal-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/studiomeyer-io/mcp-personal-suite/actions/workflows/ci.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/studiomeyer-io/mcp-personal-suite/badge)](https://scorecard.dev/viewer/?uri=github.com/studiomeyer-io/mcp-personal-suite)\n\n[Quick Start](#quick-start) · [Modules](#49-tools-6-modules) · [Config](#config) · [Privacy](#privacy) · [Security](./SECURITY.md) · [ECOSYSTEM](./ECOSYSTEM.md)\n\n</div>\n\n---\n\n## A note from us\n\nWe have been building tools and systems for ourselves for the past two years. The fact that this repo is small and has few stars is not because it is new. It is because we only just decided to share what we have built. It is not a fresh experiment, it is a long story with a recent commit.\n\nWe love building things and sharing them. We do not love social media tactics, growth hacks, or chasing stars and followers. So this repo is small. The code is real, it gets used, issues get answered. Judge for yourself.\n\nIf it helps you, sharing, testing, and feedback help us. If it could be better, an issue is more useful. If you build something with it, tell us at hello@studiomeyer.io. That genuinely makes our day.\n\nFrom a small studio in Palma de Mallorca.\n\n## Why\n\nManaging email, calendar, messaging, search, and image generation from an AI\nassistant usually means five to six separate MCP servers, each with its own\ninstall, OAuth dance, and API keys. This bundles all of it into one server that\nruns on your laptop.\n\nEverything stays local. Your credentials live in `~/.personal-suite/config.json`\nwith `0600` permissions and AES-256-GCM encryption at rest. The only data that\never leaves your machine is the direct API call to the provider you configured.\nNo signup, no backend, no tenant database.\n\nBring your own keys (BYOK) for Brave, Exa, Tavily, OpenAI, Gemini, and so on.\nMessaging uses your own bot tokens (BotFather for Telegram, Discord developer\nportal, Slack app, etc.). Email uses Gmail/Outlook OAuth or plain IMAP with\nauto-discovery for 30,000+ providers.\n\n## Quick Start\n\n```bash\n# Claude Desktop: add to claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"personal-suite\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-personal-suite\"]\n    }\n  }\n}\n\n# Claude Code\nclaude mcp add personal-suite -- npx -y mcp-personal-suite\n\n# Cursor: same stdio command as Claude\n```\n\nThen in chat:\n\n```\n\"What's configured?\"                         → suite_status\n\"Show me the quickstart guide\"               → suite_guide\n\"Set up email for info@example.com\"          → suite_setup (module: email)\n\"What's on my calendar today?\"               → calendar_list_events\n\"Send a Telegram to the team\"                → channel_send\n```\n\nFirst-time setup wizard (optional, for Google OAuth):\n\n```bash\nnpx mcp-personal-suite setup\n```\n\n## 49 Tools, 6 Modules\n\n### Email — `email_*` (15 tools)\nGmail OAuth2, Outlook OAuth2, generic IMAP/SMTP. Auto-discovery for 30K+\nproviders (Gmail, Outlook, Yahoo, iCloud, WEB.DE, GMX, T-Online, mailbox.org,\nPosteo, IONOS, Strato, Fastmail, ProtonMail Bridge, and many more). Attachments\nup to 25 MB with path-traversal protection.\n\n```\nemail_status    email_setup       email_auth       email_list       email_read\nemail_send      email_reply       email_forward    email_search     email_threads\nemail_move      email_mark_read   email_mark_unread  email_delete   email_folders\n```\n\n### Calendar — `calendar_*` (11 tools)\nGoogle Calendar (OAuth2) plus CalDAV (Apple iCloud, Nextcloud, mailbox.org,\nPosteo, Radicale, any CalDAV server). Events, availability, conflict detection,\nMeet links, daily summaries. Provider-transparent: same tools for both.\n\n```\ncalendar_status            calendar_list_events         calendar_get_event\ncalendar_create_event      calendar_update_event        calendar_delete_event\ncalendar_search_events     calendar_list_calendars      calendar_check_availability\ncalendar_upcoming          calendar_daily_summary\n```\n\n### Messaging — `channel_*` (8 tools)\nTelegram (grammy), Discord (discord.js), Slack (@slack/bolt), WhatsApp (Baileys).\nBring your own bot tokens. Send, receive, broadcast, history.\n\n> **Heads-up on WhatsApp:** Baileys is an *unofficial* reverse-engineered client.\n> It works but carries supply-chain risk and can break whenever WhatsApp changes\n> its protocol. For anything production-critical, use the official\n> [WhatsApp Business API (WABA)](https://developers.facebook.com/docs/whatsapp)\n> instead. Baileys is fine for personal/tinkering use.\n\n```\nchannel_status    channel_send       channel_receive     channel_list\nchannel_connect   channel_disconnect channel_broadcast   channel_history\n```\n\n### Search — `search_*` (7 tools)\nMulti-provider gateway (BYOK): SearXNG (self-hosted), Brave, Exa (neural),\nTavily (research with citations). Web, news, images, deep research, semantic,\ncode context.\n\n```\nsearch_web      search_news          search_images   search_deep\nsearch_semantic search_code_context  search_research\n```\n\n### Image — `image_*` (3 tools)\nBYOK image generation: OpenAI DALL-E 3, Flux via fal.ai (photorealistic),\nGoogle Gemini Imagen 3 (product shots). Auto-routing by prompt type.\n\n```\nimage_generate   image_edit   image_download\n```\n\n### System — `suite_*` (5 tools)\nOnboarding, status, setup wizard, health checks, embedded documentation, GDPR\ndelete (per-module or complete wipe).\n\n```\nsuite_status   suite_setup   suite_health   suite_guide   suite_delete\n```\n\n## Config\n\nCredentials live in a single JSON file:\n\n- **macOS / Linux:** `~/.personal-suite/config.json`\n- **Windows:** `%USERPROFILE%\\.personal-suite\\config.json`\n\nPermissions are forced to `0600` (owner read/write only). Sensitive fields\n(passwords, tokens, secrets, API keys) are encrypted with AES-256-GCM before\nbeing written. The encryption key is auto-generated in `~/.personal-suite/.key`\non first run, or you can provide your own via the `CREDENTIAL_ENCRYPTION_KEY`\nenvironment variable (32 bytes, base64).\n\nNothing ever leaves your machine except the direct API calls you make to the\nproviders you explicitly configure.\n\n## Privacy\n\n- No signup, no account, no telemetry.\n- No outbound requests until you configure a module.\n- Credentials encrypted at rest, file mode `0600`.\n- `suite_delete(module: \"all\", confirm: true)` wipes everything.\n- MIT licensed. Read the source. Fork it if you want.\n\n## Development\n\n```bash\ngit clone https://github.com/studiomeyer-io/mcp-personal-suite.git\ncd mcp-personal-suite\nnpm install\nnpm run build\nnpm test             # ~400 tests, runs in under 5s\nnpm run dev          # watch-mode stdio\nnpm run start:http   # HTTP transport on :5120\n```\n\n### HTTP Transport (self-hosted)\n\nIf you want a long-running server for multiple clients on your LAN:\n\n```bash\nmcp-personal-suite --http --port=5120\n```\n\nPoint your MCP client at `http://localhost:5120/mcp`. Streamable HTTP with\nsession management. Bind behind your own reverse proxy if you expose it beyond\nlocalhost.\n\n**Security defaults (HTTP mode):**\n- `MCP_ALLOWED_ORIGINS` — comma-separated origin whitelist for browser-based\n  MCP clients. Unset means no cross-origin requests accepted (safest). Example:\n  `MCP_ALLOWED_ORIGINS=http://localhost:3000,https://my-client.example.com`.\n- `MCP_MAX_SESSIONS` — cap on concurrent sessions (default `100`). Returns\n  `503 Retry-After: 60` beyond the limit.\n- `MCP_HOST` — bind address (default `127.0.0.1`). Change to `0.0.0.0` only\n  if you actually want to expose the server on the network.\n\n### Docker\n\n```bash\ndocker build -t personal-suite .\ndocker run -d --network host \\\n  -v $HOME/.personal-suite:/home/node/.personal-suite \\\n  -e MCP_HTTP=1 -e MCP_PORT=5120 \\\n  personal-suite\n```\n\n## Tech\n\n- TypeScript strict, no `any`, no circular deps\n- `@modelcontextprotocol/sdk@^1.26.0`\n- `imapflow` (async IMAP with auto-reconnect), `nodemailer` (SMTP)\n- `googleapis` (Gmail + Calendar OAuth)\n- `ts-caldav` (Apple iCloud, Nextcloud, Radicale)\n- `grammy`, `discord.js`, `@slack/bolt`, `@whiskeysockets/baileys`\n- `vitest` for tests, stdio + Streamable HTTP dual transport\n\n## Related\n\n- [local-memory-mcp](https://github.com/studiomeyer-io/local-memory-mcp) —\n  persistent local memory for Claude, Cursor, Codex. Pairs nicely with this.\n- [mcp-video](https://github.com/studiomeyer-io/mcp-video) — cinema-grade video\n  production (ffmpeg + Playwright).\n- [agent-fleet](https://github.com/studiomeyer-io/agent-fleet) — multi-agent\n  orchestration for Claude Code.\n- [ai-shield](https://github.com/studiomeyer-io/ai-shield) — LLM security for\n  TypeScript (prompt injection, PII, cost control).\n- [darwin-agents](https://github.com/studiomeyer-io/darwin-agents) —\n  self-evolving prompts via A/B testing.\n\n## About StudioMeyer\n\n[StudioMeyer](https://studiomeyer.io) is an AI and design studio based in Palma de Mallorca, working with clients worldwide. We build custom websites and AI infrastructure for small and medium businesses. Production stack on Claude Agent SDK, MCP and n8n, with Sentry, Langfuse and LangGraph for observability and an in-house guard layer.\n\n## License\n\n[MIT](./LICENSE). Built by [StudioMeyer](https://studiomeyer.io).",
  "bytes": 10881,
  "sha": "f87ce06434fe0a84736c07905d34d44ebd15e904b44edd3a0a4fef26168ffac4",
  "repo_slug": "studiomeyer-io/mcp-personal-suite",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_studiomeyer_personal_suite_73d1566b/readme"
}