{"id":"debe0526-949a-41f2-be8d-7b51c99dec4d","slug":"job-search-gmail-mcp","kind":"mcp","name":"job-search-gmail-mcp","summary":"","owner":"saidineshpola","repoUrl":"https://github.com/saidineshpola/job-search-gmail-mcp","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-05-23T05:28:16.000Z","addedAt":"2026-10-21T18:56:57.376Z","logoUrl":"https://avatars.githubusercontent.com/u/81302966?u=030096c5bf7438a9ceceae6c46ec38b063fce3ff&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","productivity"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-24T11:53:04.525Z","sample":false,"url":"https://conduits.dev/tools/job-search-gmail-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"gmail-theirstack"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Enhanced TheirStack Gmail MCP Server\n\nA powerful Model Context Protocol (MCP) server that combines Gmail integration with TheirStack job search capabilities, written in Python. This server enables AI assistants like Claude to search for jobs and manage email communications for your job search through natural language interaction.\n\n## 📚 Resources & Tutorials\n\n**📖 [Read the Complete Tutorial](https://medium.com/@saidines12/automate-your-job-hunt-building-a-smart-mcp-server-with-theirstack-and-gmail-01078bffe2e4)** - Step-by-step guide on Medium\n\n**🎥 [Watch the demo Video](https://www.youtube.com/watch?v=TiBvt1D4B7o&ab_channel=MachinePola)** - Demo video on YouTube\n\n## 🌟 Key Features\n\n### 💼 Job Search and Analysis\n- Search for jobs across multiple platforms via TheirStack API\n- Filter jobs by location, experience level, and skills\n- Get detailed job descriptions and requirements\n- Track application status and responses\n- Receive automated daily job alerts\n- Generate job search analytics and progress reports\n\n### 📧 Smart Email Management for Job Search\n- Send emails with customizable subject, content, and recipients\n- Read and retrieve email content with full metadata\n- Move emails to trash with confirmation\n- Mark emails as read/unread\n- Open emails directly in browser\n\n### 📝 Draft Management\n- Create draft emails for later review\n- List all draft emails\n- Edit existing drafts\n\n### 🏷️ Advanced Label Management\n- List all available labels\n- Create custom labels\n- Apply/remove labels from emails\n- Rename existing labels\n- Delete unused labels\n- Search emails by label\n\n### 📁 Folder Organization\n- Create new folders (implemented as Gmail labels)\n- Move emails between folders\n- List all available folders\n\n### 🔍 Powerful Search & Filtering\n- Search emails using Gmail's advanced query syntax\n- Create, manage, and delete email filters\n- Filter by sender, recipient, subject, content, and more\n- Customize search results with flexible parameters\n\n### 🗄️ Archive Management\n- Archive emails (remove from inbox without deleting)\n- Batch archive multiple emails matching search criteria\n- List all archived emails\n- Restore archived emails to inbox\n\n## 🚀 Getting Started\n\n### Prerequisites\n- Python 3.8+\n- Google Cloud project with Gmail API enabled\n- OAuth 2.0 credentials\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/saidineshpola/job-search-gmail-mcp.git\ncd job-search-gmail-mcp\n\n# Set up a virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install the package\nuv pip install -e .\n```\n\n> 💡 **Need help with setup?** Check out our [detailed tutorial](https://medium.com/@saidines12/automate-your-job-hunt-building-a-smart-mcp-server-with-theirstack-and-gmail-01078bffe2e4) or [video walkthrough](https://www.youtube.com/watch?v=TiBvt1D4B7o&ab_channel=MachinePola) for step-by-step instructions.\n\n### Their Stack Setup\n1. Get the API credentials from [theirstack](https://app.theirstack.com/settings/api-key) and save it inside `theirstack_api.json`:\n\n```json\n{\n    \"api_key\": \"your_theirstack_api_key_here\",\n}\n```\n\n### Google Cloud Setup\n\n1. Create a [new Google Cloud project](https://console.cloud.google.com/projectcreate)\n2. [Enable the Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)\n3. Configure the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent):\n   - Select \"External\" user type\n   - Add your email as a test user\n   - Add the scope: `https://www.googleapis.com/auth/gmail/modify`\n4. Create [OAuth 2.0 credentials](https://console.cloud.google.com/apis/credentials):\n   - Choose \"Desktop app\" as the application type\n   - Download the JSON credentials file\n\n### Configuration\n\n1. **Store OAuth Credentials**\n   ```bash\n   # Create directory for credentials\n   mkdir -p ~/.gmail-mcp\n   \n   # Move downloaded credentials file to secure location\n   mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json\n   ```\n\n2. **Configure User Profile**\n   Update the default user profile in `src/theirstack/server.py` with your details so that you don't have to give it everytime in the prompt:\n   ```python\n   COMPACT_USER_PROFILE = UserProfile(\n       name=\"AI/ML Engineer\",              # Your job title\n       skills=[                            # List your technical skills\n           \"AI/ML\", \"NLP\", \"LLM\", \"RAG\",\n           \"LangChain\", \"PyTorch\", \n           \"Python\", \"FastAPI\"\n       ],\n       preferred_locations=[\"India\", \"Remote\"],  # Your preferred work locations\n       years_of_experience=1,                    # Your years of experience\n       experience=\"Update with your professional experience summary\"\n   )\n   ```\n\n   This profile will be used to:\n   - Filter and prioritize job matches\n   - Customize job search queries\n   - Generate personalized application materials\n \n 3. **Update default mail id** \n Update the default MAil in src/gmail/server.py to your mail id for the backup if LLM doesn't know your mail id.\n\n## 🔧 Usage\n\n### Running with Claude Desktop\n\nAdd the following to your Claude Desktop configuration file (typically at `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"gmail\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"C:\\\\Users\\\\user\\\\Desktop\\\\projects\\\\gmail-mcp\",\n        \"run\",\n        \"gmail\",\n        \"--creds-file-path\",\n        \"C:\\\\Users\\\\user\\\\Desktop\\\\projects\\\\gmail-mcp\\\\client_secret_.apps.googleusercontent.com.json\",\n        \"--token-path\",\n        \"C:\\\\Users\\\\user\\\\Desktop\\\\projects\\\\gmail-mcp\\\\tokens.json\"\n      ]\n    },\n    \"jobstack\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"C:\\\\Users\\\\user\\\\Desktop\\\\projects\\\\gmail-mcp\",\n        \"run\",\n        \"jobstack\",\n        \"--api-config\",\n        \"C:\\\\Users\\\\user\\\\Desktop\\\\projects\\\\gmail-mcp\\\\theirstack_api.json\"\n      ]\n    }\n  }\n}\n```\n\n### Testing with MCP Inspector\n\nFor testing and debugging, use the MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json\n```\n\n## 🔐 Security Considerations\n\n- **Never commit credentials or token files to version control**\n- Store credentials in a secure location with appropriate permissions\n- The server will request user confirmation before performing sensitive actions\n- Review Google Cloud Console regularly for unusual activity\n- Consider using environment variables for sensitive paths\n\n## 🛠️ Architecture\n\nThis implementation features a comprehensive single-file architecture that handles all Gmail operations through the Google API client libraries. Key components include:\n\n- OAuth2 authentication with automatic token refresh\n- Comprehensive error handling and logging\n- Structured tool definitions with clear input schemas\n- Efficient email parsing and formatting\n\n## 📚 Example Prompts\n\nTry these job search-specific prompts with Claude:\n\n- \"Find ML engineering jobs posted in the last 2 days and send me the mail about it.\"\n- \"Send me a daily digest of new AI jobs in Bangalore\"\n- \"Draft an application email for the Senior ML Scientist position at Wayfair\"\n- \"Track my application status for recent jobs\"\n- \"Create a follow-up email template for applications with no response\"\n- \"Generate a weekly report of my job search progress\"\n\n## 🔄 Daily Job Search Workflow\n\n1. The server automatically fetches new job postings every 24 hours\n2. Matches are filtered based on your preferences in `theirstack_api.json`\n3. A formatted email digest is sent to your specified email address\n4. You can respond with actions like \"apply\", \"save for later\", or \"ignore\"\n5. The server helps manage applications and follow-ups automatically\n\n## 📊 Job Search Analytics\n\n- Track your application success rates\n- Monitor response times from employers\n- View job market trends in your field\n- Generate detailed progress reports\n- Set and track application goals\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📖 Learn More\n\n- **📝 [Complete Tutorial](https://medium.com/@saidines12/automate-your-job-hunt-building-a-smart-mcp-server-with-theirstack-and-gmail-01078bffe2e4)** - In-depth article explaining the architecture and implementation\n- **🎥 [Video demo](https://www.youtube.com/watch?v=TiBvt1D4B7o&ab_channel=MachinePola)** - Visual walkthrough of mcp server\n- **🔗 [Model Context Protocol](https://modelcontextprotocol.io/)** - Learn more about the MCP framework\n\n## 📄 License\n\nThis project is licensed under the GPL-3.0 License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by various MCP server implementations in the community\n- Thanks to [@theposch](https://github.com/theposch/gmail-mcp) for the gmail mcp server.\n- Built with the [Model Context Protocol](https://modelcontextprotocol.io/) framework\n- Uses Google's official API client libraries\n"}