Content
# Gemini Email Subject Generator MCP
A powerful Model Context Protocol (MCP) server that leverages Google's Gemini Flash 2 AI model to generate engaging email subjects and detailed thinking processes. This tool integrates seamlessly with Claude Desktop to provide intelligent email subject generation and advanced content creation.
## 🌟 Features
### 1. Email Tool with AI Subject Generation (`send-email`)
- Sends emails with AI-generated subjects using Gemini Flash 2
- Features:
- Dynamic subject generation based on provided prompt
- Support for HTML and plain text email content
- Image attachments with inline display capability
- Secure authentication using environment variables
- Error handling and status reporting
- Fully customizable content with rich formatting options
- Instant delivery with message tracking
### 2. Thinking Generation Tool (`generate-thinking`)
- Generates detailed thinking process text using Gemini's Flash 2 model
- Supports complex reasoning and analysis
- Saves responses with timestamps
- Customizable output directory
- Ideal for brainstorming, planning, and content creation
## 🚀 Quick Start
### Prerequisites
- Node.js (v16 or higher)
- TypeScript
- Claude Desktop
- Google Gemini API Key
- SMTP Email Account (for email functionality)
### Installation
1. Clone and setup:
```bash
git clone [your-repo-url]
cd gemini-email-subject-generator
npm install
```
2. Create `.env` file:
```env
GEMINI_API_KEY=your_api_key_here
NODEMAILER_EMAIL=your.email@gmail.com
NODEMAILER_PASSWORD=your_app_password_here
```
3. Build the project:
```bash
npm run build
```
### Claude Desktop Configuration
1. Create/Edit `%AppData%/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"Gemini Email Generator": {
"command": "node",
"args": ["path/to/gemini-email-subject-generator/dist/index.js"],
"cwd": "path/to/gemini-email-subject-generator",
"env": {
"GEMINI_API_KEY": "your_api_key_here",
"NODEMAILER_EMAIL": "your.email@gmail.com",
"NODEMAILER_PASSWORD": "your_app_password_here"
}
}
}
}
```
2. Restart Claude Desktop
## 📊 Using the Tools
### Email Sending with AI Subject Generation
```json
{
"name": "send-email",
"arguments": {
"to": "recipient@example.com",
"subjectPrompt": "Create a catchy subject line for a marketing email about our new AI-powered analytics platform",
"text": "Hello! This is the plain text version of our email.",
"html": "<h1>Hello!</h1><p>This is the <b>HTML</b> version of our email with an inline image: <img src='cid:image0'/></p>",
"images": [
{
"name": "chart.png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
]
}
}
```
> **Important Note About Email Tool**: When you use the `send-email` tool, Claude will display a confirmation message that the email was sent successfully. This confirmation message is NOT the content of the email - it's just feedback to you that the operation succeeded. The actual email sent to the recipient will contain only the content you specified in the `text` and `html` fields, with the subject generated by Gemini based on your prompt.
### Thinking Generation
```json
{
"name": "generate-thinking",
"arguments": {
"prompt": "Your complex analysis prompt here",
"outputDir": "./custom_output"
}
}
```
## 📁 Output Structure
```
output/
└── thinking/
└── gemini_thinking_[timestamp].txt
```
## 🛠️ Development
### Available Scripts
- `npm run build`: Compile TypeScript to JavaScript
- `npm run start`: Start the MCP server
- `npm run dev`: Run in development mode with ts-node
### Environment Variables
- `GEMINI_API_KEY`: Your Google Gemini API key
- `NODEMAILER_EMAIL`: Your email address for sending emails
- `NODEMAILER_PASSWORD`: Your email app password (for Gmail, use an app password)
## 🔒 Security Notes
- Store your API keys securely
- Don't share your `.env` file
- For Gmail, use app passwords instead of your main account password
- Be careful with the content of emails sent through the system
- Never include sensitive or personal information in email examples
## 🐛 Troubleshooting
### Common Issues
1. **API Key Error**
- Verify `.env` file exists
- Check API key validity
- Ensure proper environment loading
2. **Claude Desktop Connection**
- Verify config.json syntax
- Check file paths in config
- Restart Claude Desktop
3. **Email Sending Issues**
- Check that NODEMAILER_EMAIL and NODEMAILER_PASSWORD are set correctly
- For Gmail, ensure you've created an app password
- Verify that less secure app access is enabled for non-Gmail providers
- Check recipient email address format
- Ensure image data is properly formatted as data URI (data:image/type;base64,)
### Debug Mode
Add `DEBUG=true` to your `.env` file for verbose logging:
```env
GEMINI_API_KEY=your_key_here
DEBUG=true
```
## 📚 API Reference
### Email Sending Tool
```typescript
interface SendEmailParams {
to: string; // Recipient email address
subjectPrompt: string; // Prompt for generating email subject
text: string; // Plain text version of email
html?: string; // HTML version of email (optional)
images?: { // Optional images to attach
name: string; // Image filename
data: string; // Base64 encoded image data
}[];
}
```
### Thinking Generation Tool
```typescript
interface GenerateThinkingParams {
prompt: string; // Analysis prompt
outputDir?: string; // Optional output directory
}
```
## 🤝 Contributing
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## 📄 License
MIT License - See LICENSE file for details
