{"_id":"@automatearmy/email-reader-mcp","name":"@automatearmy/email-reader-mcp","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.3":{"name":"@automatearmy/email-reader-mcp","version":"1.0.3","type":"module","bin":{"email-reader-mcp":"build/index.js"},"scripts":{"build":"tsc && chmod 755 build/index.js","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage"},"keywords":["mcp","model-context-protocol","claude","gmail","email","calendar","ai","llm","integration"],"author":"","license":"ISC","description":"MCP server for reading Gmail messages via IMAP","dependencies":{"@modelcontextprotocol/sdk":"^1.20.0","imapflow":"^1.0.199","mailparser":"^3.7.5","zod":"^3.25.76"},"devDependencies":{"@types/mailparser":"^3.4.6","@types/node":"^24.7.2","typescript":"^5.9.3"},"_id":"@automatearmy/email-reader-mcp@1.0.3","gitHead":"4e588b60ba7a8beeb91d0a854c227ebbe645c4ab","_nodeVersion":"22.9.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-/nAAwsMa2sjvMTskyWlDRgP5jwD6sER/7mGJkw9H58Mr/Yw4R1Twx1VLR+c8Q8eGTLtGMhGGFD1jJe3K4nnAfQ==","shasum":"57edaa893dbc63ebaa93a106aa05c40a48347628","tarball":"https://registry.npmjs.org/@automatearmy/email-reader-mcp/-/email-reader-mcp-1.0.3.tgz","fileCount":10,"unpackedSize":19664,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCywNjFuVVJbMweCBXekC1Oz33Cf/czcud+27GVpjN31wIgbH7T2adgZHIgWFiAGunJGHJmgbNmVAa4pCN/+zMx2T0="}]},"_npmUser":{"name":"automatearmy","email":"team@automatearmy.com"},"directories":{},"maintainers":[{"name":"automatearmy","email":"team@automatearmy.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/email-reader-mcp_1.0.3_1760714759902_0.41161585072177553"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-17T15:25:59.785Z","1.0.3":"2025-10-17T15:26:00.105Z","modified":"2025-10-17T15:26:00.459Z"},"maintainers":[{"name":"automatearmy","email":"team@automatearmy.com"}],"description":"MCP server for reading Gmail messages via IMAP","keywords":["mcp","model-context-protocol","claude","gmail","email","calendar","ai","llm","integration"],"license":"ISC","readme":"# Email Reader MCP\n\nA Model Context Protocol (MCP) server that enables Claude Desktop or any Client to read and search your Gmail messages via IMAP. Perfect for AI-powered email workflows, automation, and intelligent email management.\n\n## 🚀 Quick Start\n\n### 1. Prerequisites\n\n- **Node.js** (v18 or higher)\n- **Gmail account** with IMAP enabled\n- **App Password** (if using 2-factor authentication)\n\n### 2. Gmail Setup\n\n1. **Enable IMAP in Gmail:**\n   - Go to Gmail Settings → See all settings → Forwarding and POP/IMAP\n   - Enable \"IMAP access\"\n   - Save changes\n\n2. **Create App Password (if using 2FA):**\n   - Visit [Google App Passwords](https://myaccount.google.com/apppasswords)\n   - Select \"Mail\" for the app and \"Other (Custom name)\" for the device\n   - Name it \"Claude Desktop MCP\"\n   - Copy the generated password\n\n### 3. MCP Server Configuration\n\nAdd this to your Claude Desktop configuration file:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"email-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@automatearmy/email-reader-mcp\"]\n    }\n  }\n}\n```\n\n### 4. Environment Setup\n\nCreate a `.env` file in your home directory or project folder:\n\n```bash\n# Copy the example file\ncp .env.example .env\n\n# Edit with your credentials\nUSER_EMAIL=\"your-email@gmail.com\"\nUSER_PASS=\"your-app-specific-password\"\n```\n\n### 5. Restart Claude Desktop\n\nRestart Claude Desktop to load the new MCP server. You can now ask Claude to read your emails!\n\n## 📧 Available Tools\n\n### `get-messages`\n\nFetch and filter email messages from your Gmail inbox with powerful search capabilities.\n\n#### Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `limit` | number | 10 | Maximum number of messages to fetch |\n| `includeFullContent` | boolean | false | Include full email body (default: 500-char preview) |\n| `dateFrom` | string | - | Filter messages from this date (ISO format: \"2024-01-01\") |\n| `dateTo` | string | - | Filter messages until this date (ISO format) |\n| `unreadOnly` | boolean | false | Only fetch unread messages |\n| `from` | string | - | Filter by sender email address |\n| `subject` | string | - | Filter by subject (partial match) |\n\n#### Response Format\n\n```json\n{\n  \"messages\": [\n    {\n      \"uid\": 12345,\n      \"subject\": \"Email Subject\",\n      \"from\": \"sender@example.com\",\n      \"to\": \"recipient@example.com\",\n      \"date\": \"2024-01-15T10:30:00.000Z\",\n      \"body\": \"Email content...\",\n      \"flags\": [\"\\\\Seen\"]\n    }\n  ],\n  \"count\": 1,\n  \"filters\": {\n    \"limit\": 10,\n    \"includeFullContent\": false,\n    \"unreadOnly\": false\n  }\n}\n```\n\n## 💡 Usage Examples\n\n### Basic Email Reading\n```\n\"Show me my latest 5 emails\"\n```\n\n### Unread Messages Only\n```\n\"Get all unread messages from today\"\n```\n\n### Advanced Filtering\n```\n\"Find emails from notifications@github.com about 'pull request' in the last week\"\n```\n\n### Full Content Search\n```\n\"Show me the complete content of the 3 most recent emails from my boss\"\n```\n\n### Date Range Queries\n```\n\"Get all emails from December 2024 with 'invoice' in the subject\"\n```\n\n## 🔒 Security Best Practices\n\n- **Never commit `.env` files** to version control\n- **Use App Passwords** instead of your main Gmail password\n- **Limit access** to only necessary email folders\n- **Regularly rotate** your app passwords\n- **Monitor access** in your Google account security settings\n\n## ⚡ Performance Tips\n\n- Use **date ranges** to reduce processing time\n- Set **reasonable limits** (default: 10 messages)\n- Use **preview mode** (`includeFullContent: false`) for initial searches\n- Apply **specific filters** (sender, subject) to narrow results\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n**\"Authentication failed\"**\n- Verify IMAP is enabled in Gmail settings\n- Check that you're using an App Password (not regular password)\n- Ensure email and password are correctly set.\n\n**\"No messages found\"**\n- Check your search criteria aren't too restrictive\n- Verify the date format is correct (ISO string)\n- Try without filters first to test connectivity\n\n**\"Connection timeout\"**\n- Check your internet connection\n- Verify Gmail IMAP servers are accessible\n- Try restarting Claude Desktop\n\n\n\n## 🏗️ Development\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/automatearmy/email-reader-mcp.git\ncd email-reader-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # MCP server entry point\n├── imap/\n│   └── index.ts          # IMAP client configuration\n└── tools/\n    └── get-messages/\n        ├── schema.ts     # Zod validation schema\n        └── index.ts      # Tool handler implementation\n```\n\n## 📄 License\n\nISC License - see [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## 📞 Support\n\nFor issues and questions:\n- Create an issue on GitHub\n- Check the troubleshooting section above\n- Review the [MCP documentation](https://modelcontextprotocol.io/)\n\n---\n\n**Built by [Automate Army](https://automatearmy.com)** - Empowering AI workflows with robust integrations.\n","readmeFilename":"README.md","_rev":"1-7c0c53b002845a7abbe79223c3aabd59"}