# Zoom MCP Server

A FastMCP Model Context Protocol server that provides intelligent monitoring and management of Zoom rooms across multiple sites with smart location resolution.

## 🚀 Features (New!)

- **5 Powerful Tools** for comprehensive Zoom room management
- **Smart Location Resolution** with fuzzy matching (e.g., "SF1", "DEN1", "Floor 3")
- **Denver Building Aliases** - Special hardcoded mappings for room naming compatibility
- **Efficient API Usage** - Single call for company-wide queries vs. multiple location-specific calls
- **OAuth 2.0 Authentication** with automatic token refresh and file-based caching
- **Hierarchical Location Discovery** - Understands campus → building → floor relationships
- **User-Friendly Confirmations** - Clear messages explaining what was resolved

## 🛠️ Tools Available

### `test_zoom_connection`
Test Zoom API authentication and connection status.
```bash
# Usage: Verify credentials are working
mcp call test_zoom_connection --params '{}' uv run src/server.py
```

### `get_zoom_sites` 
Get all Zoom locations with hierarchy and aliases.
```bash
# Usage: Understand available locations and relationships
mcp call get_zoom_sites --params '{}' uv run src/server.py
```

### `get_zoom_rooms`
Get Zoom rooms with optional smart location filtering.

**⚡ IMPORTANT**: For maximum efficiency with company-wide queries (e.g., "find offline rooms anywhere"), omit `location_query` to make a single API call.

```bash
# Company-wide (EFFICIENT - single API call)
mcp call get_zoom_rooms --params '{}' uv run src/server.py

# Location-specific (multiple API calls)
mcp call get_zoom_rooms --params '{"location_query":"SF1"}' uv run src/server.py
mcp call get_zoom_rooms --params '{"location_query":"DEN1"}' uv run src/server.py
mcp call get_zoom_rooms --params '{"location_query":"Floor 3"}' uv run src/server.py
```

### `get_room_details`
Get detailed information about a specific room.
```bash
# Usage: Deep dive into specific room configuration
mcp call get_room_details --params '{"room_id":"ROOM_ID_HERE"}' uv run src/server.py
```

### `resolve_location`
Debug tool to test location resolution without fetching rooms.
```bash
# Usage: Debug how location queries get resolved
mcp call resolve_location --params '{"location_query":"DEN2"}' uv run src/server.py
```

## 📍 Smart Location Resolution

The server understands various location query patterns:

| Query Pattern | Example | What It Resolves |
|---------------|---------|------------------|
| Campus codes | `SF1`, `NYC`, `DEN` | Entire campus with all buildings/floors |
| Building numbers | `Building 1`, `DEN1` | Specific building or hardcoded alias |
| Floor numbers | `Floor 1`, `3F` | All floors with that number across sites |
| Partial names | `Denver`, `Francisco` | Best fuzzy match |

### Special Denver Building Aliases

Due to Zoom's location hierarchy vs. room naming patterns, Denver has special hardcoded mappings:

- **`DEN1`** → Denver Building 1 (Floor 3) → Rooms: `DEN-1-101`, `DEN-1-102`, etc.
- **`DEN2`** → Denver Building 2 (T3F3, T3F5, T3F6) → Rooms: `DEN-2-201`, `DEN-2-202`, etc.

## 🔧 Installation & Setup

### Prerequisites
- Python 3.10+
- UV package manager
- Zoom Pro/Business account with API access

### 1. Clone Repository
```bash
git clone https://github.com/chadkunsman/zoom-mcp.git
cd zoom-mcp
```

### 2. Install Dependencies
```bash
uv pip install -e .
```

### 3. Zoom API Configuration

1. Create a **Server-to-Server OAuth** app in [Zoom Marketplace](https://marketplace.zoom.us/)
2. Add required scope: `room:read:admin`
3. Get your credentials: Account ID, Client ID, Client Secret

### 4. Configure Credentials

Create `.env` file:
```bash
ZOOM_ACCOUNT_ID=your_account_id_here
ZOOM_CLIENT_ID=your_client_id_here
ZOOM_CLIENT_SECRET=your_client_secret_here
```

### 5. Test Installation
```bash
# Install MCPTools for testing
brew tap f/mcptools && brew install mcp

# Test the server
mcp tools uv run src/server.py
mcp call test_zoom_connection --params '{}' uv run src/server.py
```

## 🔌 MCP Client Configuration

### For Claude Desktop and Similar MCP Clients

Add to your MCP client configuration:

#### Using Environment Variables (Recommended)
```json
{
  "mcpServers": {
    "zoom-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/zoom-mcp",
        "src/server.py"
      ],
      "env": {
        "ZOOM_ACCOUNT_ID": "your_account_id_here",
        "ZOOM_CLIENT_ID": "your_client_id_here",
        "ZOOM_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}
```

#### Using Command-Line Arguments
```json
{
  "mcpServers": {
    "zoom-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/zoom-mcp",
        "src/server.py",
        "--zoom-account-id",
        "your_account_id_here",
        "--zoom-client-id", 
        "your_client_id_here",
        "--zoom-client-secret",
        "your_client_secret_here"
      ]
    }
  }
}
```

## 💡 Usage Examples

### Find All Offline Rooms (Efficient)
"Are any Zoom rooms offline anywhere in the company?"
→ Uses `get_zoom_rooms` without location_query (single API call)

### Check Specific Location
"Show me all rooms in San Francisco"
→ Uses `get_zoom_rooms` with `location_query: "SF1"`

### Debug Location Resolution
"How would 'DEN2' be resolved?"
→ Uses `resolve_location` to see what locations match

### Room Status by Building
"What's the status of Denver Building 1 rooms?"
→ Uses `get_zoom_rooms` with `location_query: "DEN1"`

## 🏗️ Architecture

```
zoom-mcp/
├── src/
│   ├── server.py              # Main MCP server with 5 tools
│   └── config/                # Configuration modules
│       ├── settings.py        # Environment & auth configuration
│       ├── zoom_auth.py       # OAuth token management
│       ├── zoom_hierarchy.py  # Location discovery & relationships
│       └── zoom_fuzzy.py      # Smart location resolution
├── docs/                      # Comprehensive documentation
└── test_server.py            # Direct testing script
```

### Key Design Patterns

- **Import Inside Functions**: Configuration modules imported inside tool functions to avoid timing issues
- **Multi-Level Token Caching**: Memory cache + file persistence with 1-hour expiration and 5-minute buffer
- **Hierarchical Discovery**: Automatic campus → building → floor relationship building
- **Hybrid Resolution**: Hardcoded Denver aliases + dynamic fuzzy matching for other sites

## 🧪 Testing

### MCPTools Testing
```bash
# List all tools
mcp tools uv run src/server.py

# Test authentication
mcp call test_zoom_connection --params '{}' uv run src/server.py

# Interactive testing
mcp shell uv run src/server.py
```

### Direct Script Testing
```bash
python test_server.py
```

## 📚 Documentation

Comprehensive documentation available in `docs/`:

- [Quick Start Guide](docs/quickstart.md) - Setup and basic usage
- [Authentication Guide](docs/authentication.md) - OAuth implementation details
- [Testing Guide](docs/testing.md) - MCPTools usage and examples
- [Best Practices](docs/best-practices.md) - Zoom-specific patterns
- [Advanced Features](docs/zoom-features.md) - Deep dive into capabilities

## 🔒 Security

- Credentials stored in `.env` files (not committed to git)
- Token caching with secure file permissions
- Bearer token automatic refresh
- Error messages don't expose sensitive information

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with MCPTools
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License.

## 🆘 Troubleshooting

### Common Issues

1. **"Zoom credentials not configured"**
   - Verify `.env` file exists with correct variables
   - Check environment variable names match exactly

2. **"Token request failed: 401"**
   - Verify Zoom app credentials are correct
   - Ensure app has `room:read:admin` scope
   - Confirm app is Server-to-Server OAuth type

3. **"No location matches found"**
   - Check spelling of location query
   - Use `get_zoom_sites` to see available locations
   - Test with `resolve_location` to debug fuzzy matching

4. **Import timing issues**
   - Configuration modules imported inside tool functions
   - Never import config at module level before `initialize_config()`

### Debug Commands
```bash
# Test connection
mcp call test_zoom_connection --params '{}' uv run src/server.py

# List all sites
mcp call get_zoom_sites --params '{}' uv run src/server.py

# Debug location resolution
mcp call resolve_location --params '{"location_query":"your_query"}' uv run src/server.py
```

---

Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [Model Context Protocol](https://modelcontextprotocol.io/).