Cold Email Assistant MCP Server

How to use

Use an MCP client to connect to this server and perform end-to-end email outreach. You can parse a job posting, load your resume, generate a tailored cold email, and either save it as a draft or send it directly to a recruiter. Focus on practical steps: parse, load, generate, draft, and optionally send.

How to install

Prerequisites: you need Python 3.8 or newer and a Gmail account with App Passwords enabled. Make sure you have your resume ready as resume.pdf.

1) Clone the MCP server repository and install dependencies.

# Clone the repository
git clone <repository-url>
cd cold-email-assistant

# Install dependencies
pip install fastmcp python-docx

2) Configure Gmail app password usage by creating an app password for Mail in your Google account and copy it to the server configuration as shown in the config snippet.

3) Add the MCP server configuration to Claude Desktop. Create or edit the Claude Desktop config file and include the Python path to the MCP script.

{
  "mcpServers": {
    "cold-email": {
      "command": "python",
      "args": ["/path/to/your/cold_email_mcp.py"]
    }
  }
}

Additional configuration and runtime details

Update your MCP script to use your Gmail credentials and resume path. The following snippet shows where to place these values.

sender_email: str = '[email protected]'
sender_password: str = 'your-app-password'
resume_path: str = "resume.pdf"

How to start using the server with Claude Desktop

After configuring the MCP server, you can issue commands from Claude Desktop to drive the workflow. Start by parsing a job posting from a WhatsApp message, then load your resume, generate a personalized email, and finally save it as a draft or send it.

Security and reliability notes

Use Gmail App Passwords for authentication and keep app passwords secure. The server communicates over TLS when sending emails. Consider moving credentials to environment variables for production deployments.

Troubleshooting

Error: Resume file not found. Ensure resume.pdf is in the same directory as the MCP script and that resume_path points to the correct location.

Authentication failed. Verify 2FA is enabled, generate a new App Password, and update sender_password in your script.

Connection refused. Check internet connectivity, confirm Gmail SMTP/IMAP is enabled, and review firewall settings.

Draft not appearing in Gmail. Wait a moment, refresh, check the All Mail folder, and ensure IMAP is enabled in Gmail settings.

Notes and tips

Review drafts in Gmail before sending to ensure accuracy. Store your email template in prompt.docx to maintain consistent messaging, and you can attach your resume.pdf automatically to all outgoing messages.

Example workflow

1. You: Parse a job posting from WhatsApp. 2. Claude: Extracts company, role, email, and requirements. 3. You: Load your resume. 4. Claude: Reads resume content. 5. You: Generate a personalized email for the role. 6. Claude: Creates a tailored email. 7. You: Save as draft to [email protected]. 8. Claude: Saves to Gmail Drafts with the resume attached. 9. Review the draft in Gmail and send if ready.

parse_job_message

Extracts structured data from job postings including company, role, email, location, stipend, graduation year, and requirements.

load_resume

Reads your resume from a .docx file to enable AI personalization in emails.

load_prompt

Loads custom email templates from a .docx file for consistent messaging.

send_email_tool

Sends emails with resume attachments via Gmail SMTP.

save_to_draft_tool

Saves emails to Gmail Drafts for review before sending.