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

1. Create a Server-to-Server OAuth app in Zoom Marketplace
2. Add required scope: room:read:admin
3. 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

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

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