# Outlook MCP Server

A **Model Context Protocol (MCP)** server for Microsoft Outlook integration that provides comprehensive email, contact, calendar, and folder management capabilities through the Microsoft Graph API.

## 🚀 Quick Start

### Prerequisites

- Python 3.8 or higher
- uv package manager
- Microsoft Graph API access via [Nango](https://nango.dev)
- Valid Outlook/Microsoft 365 account

### Installation

1. **Clone and setup:**
   ```bash
   git clone <repository-url>
   cd outlook-mcp
   uv install -e .
   ```

2. **Configure environment variables:**
   Create a `.env` file or set these environment variables:
   ```bash
   NANGO_CONNECTION_ID=your_connection_id
   NANGO_INTEGRATION_ID=your_integration_id
   NANGO_BASE_URL=your_nango_base_url
   NANGO_SECRET_KEY=your_secret_key
   ```

3. **Test the server:**
   ```bash
   uv run python outlook_mcp_server.py --help
   ```

## 🔧 MCP Client Configuration

### Claude Desktop Configuration

Add this to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%/Claude/claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "outlook": {
      "command": "uvx",
      "args": [
        "git+https://github.com/ampcome-mcps/outlook-mcp.git",
      ],
      "env": {
        "NANGO_CONNECTION_ID": "your_connection_id",
        "NANGO_INTEGRATION_ID": "your_integration_id",
        "NANGO_BASE_URL": "your_nango_base_url",
        "NANGO_SECRET_KEY": "your_secret_key"
      }
    }
  }
}
```

### Other MCP Clients

For other MCP clients, use:
- **Command:** `uv`
- **Args:** `["run", "python", "outlook_mcp_server.py"]`
- **Working Directory:** Path to the outlook-mcp directory
- **Transport:** stdio
- **Environment:** Set the required Nango variables

## 📧 Available Tools (26 Total)

### Email Management (6 tools)
- **`send_email`** - Send emails with TO/CC/BCC, HTML/text content, attachments
- **`create_draft_email`** - Create draft emails for later editing
- **`send_draft_email`** - Send existing draft emails
- **`get_draft_emails`** - Retrieve all draft emails
- **`update_draft_email`** - Modify existing draft emails
- **`delete_draft_email`** - Remove draft emails

### Contact Management (5 tools)
- **`create_contact`** - Add new contacts with full details
- **`get_all_contacts`** - Retrieve all contacts
- **`get_contact_details`** - Get specific contact information
- **`update_contact`** - Modify existing contact details
- **`delete_contact`** - Remove contacts

### Calendar Management (9 tools)
- **`get_all_calendars`** - List all calendars
- **`get_calendar_details`** - Get specific calendar information
- **`create_calendar`** - Create new calendars with custom colors
- **`update_calendar`** - Modify calendar properties
- **`delete_calendar`** - Remove calendars
- **`get_all_events`** - Retrieve events from calendars
- **`get_event_details`** - Get specific event information
- **`create_event`** - Schedule new events with attendees
- **`delete_event`** - Remove calendar events

### Folder Management (6 tools)
- **`get_all_folders`** - List all mail folders
- **`get_folder_details`** - Get specific folder information
- **`create_folder`** - Create new mail folders (with nesting)
- **`update_folder`** - Rename folders
- **`delete_folder`** - Remove folders
- **`get_many_folders`** - Batch retrieve multiple folders

## 💡 Usage Examples

### Send an Email
```json
{
  "tool": "send_email",
  "arguments": {
    "subject": "Project Update",
    "content": "<h1>Hello!</h1><p>Here's the latest update...</p>",
    "to_recipients": ["colleague@company.com"],
    "cc_recipients": ["manager@company.com"],
    "importance": "high"
  }
}
```

### Create a Contact
```json
{
  "tool": "create_contact",
  "arguments": {
    "given_name": "John",
    "surname": "Doe",
    "email_addresses": "john.doe@company.com,john@personal.com",
    "company_name": "Acme Corp",
    "job_title": "Software Engineer"
  }
}
```

### Schedule a Meeting
```json
{
  "tool": "create_event",
  "arguments": {
    "subject": "Weekly Team Meeting",
    "start_datetime": "2024-01-15T10:00:00",
    "end_datetime": "2024-01-15T11:00:00",
    "attendees": ["team@company.com"],
    "location": "Conference Room A",
    "body_content": "Discussing project milestones"
  }
}
```

## 🏗️ Project Structure

```
outlook-mcp/
├── src/outlook_mcp/
│   ├── __init__.py
│   ├── server.py              # Main MCP server implementation
│   ├── connection.py          # Nango API connection handling
│   └── tools/
│       ├── __init__.py
│       ├── email.py           # Email management tools
│       ├── contacts.py        # Contact management tools
│       ├── calendar.py        # Calendar and event tools
│       └── folders.py         # Folder management tools
├── outlook_mcp_server.py      # Standalone server entry point
├── main.py                    # Alternative entry point
├── pyproject.toml            # Package configuration with uv
├── uv.lock                   # uv lockfile for reproducible builds
├── README.md                 # This documentation
└── .env                      # Environment variables (create this)
```

## 🔒 Security & Authentication

This server uses **Nango** for secure Microsoft Graph API authentication:

1. **No direct credential storage** - All auth handled by Nango
2. **Token management** - Automatic token refresh and management
3. **Secure communication** - HTTPS-only API communication
4. **Environment-based config** - Sensitive data in environment variables

## 🐛 Troubleshooting

### Common Issues

1. **"Missing environment variables"**
   - Ensure all 4 Nango variables are set in your Claude configuration
   - Check `.env` file exists and is properly formatted for local development

2. **"Connection failed"**
   - Verify Nango integration is active
   - Check internet connectivity
   - Validate Nango credentials

3. **"Tool execution failed"**
   - Check Microsoft Graph API permissions
   - Verify Outlook account has necessary access
   - Review error messages in Claude Desktop logs

4. **"uv command not found"**
   - Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
   - Or via pip: `pip install uv`

### Debug Mode

For local development, run with verbose output:
```bash
uv run python outlook_mcp_server.py 2>debug.log
```

### Testing Connection

```bash
uv run python -c "from outlook_mcp.connection import get_access_token; print('✅ Connection successful!' if get_access_token() else '❌ Connection failed')"
```

## 🧪 Development & Testing

### Local Development

1. **Install in development mode:**
   ```bash
   uv install -e .
   ```

2. **Run tests:**
   ```bash
   uv run pytest tests/
   ```

3. **Check tool functionality:**
   ```bash
   uv run python -c "from outlook_mcp.tools.email import get_draft_emails; print(get_draft_emails())"
   ```

### Creating Custom Tools

1. Add your tool function to the appropriate module in `tools/`
2. Update the server's tool list in `server.py`
3. Add proper input schema validation
4. Test with MCP client

## 📋 Requirements

- **Python 3.8+**
- **uv >= 0.1.0** - Fast Python package installer and resolver
- **mcp >= 1.0.0** - Model Context Protocol library
- **requests >= 2.32.4** - HTTP client
- **python-dotenv >= 1.1.1** - Environment variable management

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-tool`
3. Make your changes with tests
4. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🔗 Related Links

- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [Microsoft Graph API Documentation](https://docs.microsoft.com/en-us/graph/)
- [Nango Integration Platform](https://nango.dev)
- [Claude Desktop MCP Configuration](https://docs.anthropic.com/claude/desktop)
- [uv Package Manager](https://github.com/astral-sh/uv)

## 📞 Support

For issues and questions:
1. Check the troubleshooting section above
2. Review the GitHub issues
3. Create a new issue with detailed information

---

**Built with ❤️ for seamless Outlook integration via MCP**