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.

# 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.

# 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.

# 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.

# 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.

# 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

git clone https://github.com/chadkunsman/zoom-mcp.git
cd zoom-mcp

2. Install Dependencies

uv pip install -e .

3. Zoom API Configuration

Create a Server-to-Server OAuth app in Zoom Marketplace
Add required scope: room:read:admin
Get your credentials: Account ID, Client ID, Client Secret

4. Configure Credentials

Create .env file:

ZOOM_ACCOUNT_ID=your_account_id_here
ZOOM_CLIENT_ID=your_client_id_here
ZOOM_CLIENT_SECRET=your_client_secret_here

5. Test Installation

# 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)

{
  "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

{
  "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

# 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

python test_server.py

📚 Documentation

Comprehensive documentation available in docs/:

Quick Start Guide - Setup and basic usage
Authentication Guide - OAuth implementation details
Testing Guide - MCPTools usage and examples
Best Practices - Zoom-specific patterns
Advanced Features - 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

Fork the repository
Create a feature branch
Make your changes
Test with MCPTools
Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Troubleshooting

Common Issues

"Zoom credentials not configured"
- Verify .env file exists with correct variables
- Check environment variable names match exactly
"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
"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
Import timing issues
- Configuration modules imported inside tool functions
- Never import config at module level before initialize_config()

Debug Commands

# 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 and the Model Context Protocol.