CLAUDE-SETUP.md•5.67 kB
# Claude Configuration Guide - FastMail MCP Server
Complete setup guide for using the dockerized FastMail MCP Server with both Claude Code and Claude Desktop.
## ✅ Current Status
Your FastMail MCP Server has been successfully dockerized and configured:
- ✅ Docker image built (`fastmail-mcp-server:latest`)
- ✅ Bridge scripts created for Claude Code
- ✅ MCP configuration updated in `~/.mcp.json`
- ✅ Container tested and working (24 tools available)
## Configuration for Claude Code (CLI)
Your Claude Code is already configured! The MCP server is set up in `~/.mcp.json`:
```json
{
"mcpServers": {
"fastmail-server": {
"command": "/Users/ceverson/Development/email_organization/core/mcp-simple-bridge.sh",
"args": []
}
}
}
```
### Test Claude Code Integration
```bash
# Start Claude Code and test
claude
# Try: /mcp list
# Should show fastmail-server as connected
```
## Configuration for Claude Desktop (Mac/iOS)
Claude Desktop uses a different configuration location. Choose one of these methods:
### Method 1: Update Claude Desktop Config
1. **Locate Claude Desktop config file** (one of these locations):
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
~/claude_desktop_config.json
~/.config/claude-desktop/config.json
```
2. **Update the config file**:
```json
{
"mcpServers": {
"fastmail-server": {
"command": "/Users/ceverson/Development/email_organization/core/mcp-simple-bridge.sh",
"args": []
}
}
}
```
3. **Restart Claude Desktop**
### Method 2: Use HTTP Transport (If stdio doesn't work)
If Claude Desktop has issues with the stdio bridge, you can use HTTP transport:
1. **Start HTTP version**:
```bash
cd /Users/ceverson/Development/email_organization/core
docker-compose -f docker-compose-http.yml up -d
```
2. **Configure Claude Desktop for HTTP**:
```json
{
"mcpServers": {
"fastmail-server": {
"command": "curl",
"args": ["-X", "POST", "http://localhost:3000/mcp", "-H", "Content-Type: application/json", "-d", "@-"]
}
}
}
```
## Quick Start Commands
### Start the MCP Server
```bash
# Method 1: Direct docker run (recommended for Claude Code)
cd /Users/ceverson/Development/email_organization/core
./mcp-simple-bridge.sh # This is what Claude Code calls
# Method 2: HTTP version for Claude Desktop
docker-compose -f docker-compose-http.yml up -d
```
### Test the Server
```bash
# Test stdio version
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | ./mcp-simple-bridge.sh
# Test HTTP version (if running)
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
```
## Available MCP Tools
Your FastMail MCP server provides 24 tools:
### Email Management
- `list_mailboxes` - List all mailboxes
- `list_emails` - List emails with pagination
- `get_email` - Get full email details
- `search_emails` - Search emails by query
- `send_email` - Send new emails
- `reply_to_email` - Reply to emails
### AI-Powered Features
- `smart_email_analysis` - Find actionable emails
- `generate_ai_reply` - AI-powered reply generation
- `analyze_writing_style` - Learn your writing style
- `comprehensive_email_summary` - Generate email summaries
- `adaptive_user_learning` - Learn user patterns
### Organization & Automation
- `organize_emails` - Auto-organize into folders
- `achieve_inbox_zero` - Aggressive inbox cleanup
- `setup_simple_labels` - Create 13-label structure
- `categorize_with_simple_labels` - Auto-categorize
- `migrate_to_hierarchy` - Migrate to new structure
### Contacts & Calendar
- `manage_contacts` - Smart contact management
- `list_contacts` - List existing contacts
- `manage_calendar` - Calendar event management
### Advanced Features
- `summarize_news` - News digest from emails
- `review_archived_emails` - Review archived items
- `optimize_ai_prompts` - Optimize AI prompts
- `universal_setup_wizard` - Onboarding wizard
- `analyze_hierarchical_structure` - Structure analysis
## Troubleshooting
### Claude Code Issues
```bash
# Check if server is accessible
./mcp-simple-bridge.sh
# Should show startup messages and wait for input
# Check MCP configuration
cat ~/.mcp.json
# Test with simple command
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | ./mcp-simple-bridge.sh
```
### Claude Desktop Issues
1. **Check config file location**:
```bash
find ~/Library -name "*claude*" -type d 2>/dev/null
find ~/ -name "*claude_desktop_config.json" 2>/dev/null
```
2. **Verify Docker is running**:
```bash
docker ps | grep fastmail
```
3. **Check container logs**:
```bash
docker logs fastmail-mcp-server-http
```
### Permission Issues
If you get permission errors:
```bash
# Make sure scripts are executable
chmod +x /Users/ceverson/Development/email_organization/core/*.sh
# Check Docker permissions
docker run hello-world
```
## Security Notes
- API tokens are loaded from `.env` file
- Container runs as non-root user
- Read-only filesystem for security
- Memory and CPU limits applied
- No network ports exposed (stdio version)
## Next Steps
1. **Test with Claude Code**: Start a new Claude Code session and try `/mcp list`
2. **Configure Claude Desktop**: Update config file and restart the app
3. **Try a few commands**: Start with `list_mailboxes` or `smart_email_analysis`
4. **Set up automation**: Use `achieve_inbox_zero` or `organize_emails`
Your FastMail MCP server is ready to use with both Claude clients!
