Webex Calling Server

An MCP (Model Context Protocol) server that lets you manage your entire Webex Calling infrastructure using natural language through an AI assistant like Claude.

Built for Cisco partners and network engineers to demonstrate the power of AI-driven network administration.

Prerequisites

1. Node.js (v18 or later)

Node.js is the runtime needed to execute the MCP server. You must install it on every machine where you want to run the server.

brew install node

2. Git

Git is needed to clone this repository.

git --version

3. A Webex Full Admin account

4. An AI client that supports MCP

• VS Code with GitHub Copilot (Chat agent mode) — Download VS Code
• Claude Desktop — Download Claude Desktop

Demo Scenarios (Live with partners)

Available Tools (35+)

People & Users

• list_people — List/search users with calling data
• get_person — Get detailed user info
• find_users_without_phones — Audit users without phone numbers

Call Forwarding & Voicemail

• get_call_forwarding / update_call_forwarding — Manage forwarding rules
• get_voicemail / update_voicemail — Configure voicemail
• redirect_calls_to_voicemail — Quick call intercept (great for demos!)
• set_do_not_disturb — Enable/disable DND

Hunt Groups

• list_hunt_groups / get_hunt_group — View hunt groups
• create_hunt_group — Create with agents & routing policy
• update_hunt_group / delete_hunt_group — Manage existing groups

Call Queues

• list_call_queues / get_call_queue — View queues
• create_call_queue — Create with agents & queue settings
• update_call_queue / delete_call_queue — Manage existing queues

Phone Numbers

• list_numbers — List all numbers with filtering
• find_available_numbers — Find unassigned numbers

Call Analytics

• get_call_history — Raw CDR data
• get_missed_calls_report — Formatted missed call analysis with charts-ready data

Locations & Schedules

• list_locations / get_location — View office locations
• list_schedules — View business hours & holiday schedules
• create_holiday_schedule — Create holiday schedules
• list_auto_attendants / get_auto_attendant — View IVR menus

Devices & Workspaces

• list_devices / get_device — View device inventory
• list_workspaces — View conference rooms & shared spaces
• get_caller_id / update_caller_id — Manage caller ID settings

Organization Contacts & Groups

• list_org_contacts / get_org_contact — View org directory contacts
• create_org_contact — Add external contacts to the org directory
• update_org_contact / delete_org_contact — Manage existing contacts
• list_groups — List groups (used to scope contact visibility)

Quick Start

1. Clone the repository

cd ~/Desktop
git clone https://github.com/rochaussee/webex-calling-mcp.git
cd webex-calling-mcp

cd $HOME\Desktop
git clone https://github.com/rochaussee/webex-calling-mcp.git
cd webex-calling-mcp

2. Create a Webex Integration

1. Go to developer.webex.com
2. Sign in with your Webex Full Admin account
3. Create a new Integration and note the Client ID and Client Secret
4. Set the Redirect URI to http://localhost:22991/callback
5. Select the required scopes (see src/auth.ts for the default list)

3. Install dependencies & Build

These commands are the same on macOS and Windows:

npm install
npm run build

Note: You must be in the project folder (e.g. cd webex-calling-mcp) before running these commands.

4. Authenticate (one-time setup)

WEBEX_CLIENT_ID=xxx WEBEX_CLIENT_SECRET=yyy npm run auth

$env:WEBEX_CLIENT_ID="xxx"
$env:WEBEX_CLIENT_SECRET="yyy"
npm run auth

Replace xxx and yyy with the Client ID and Client Secret from step 2.

What happens:

1. Your browser opens the Webex login page
2. You sign in with your Webex Full Admin account
3. Webex sends back authentication tokens to the local server
4. Tokens are saved locally:
   • macOS / Linux: ~/.webex-mcp/tokens.json
   • Windows: %USERPROFILE%\.webex-mcp\tokens.json

About tokens:

• Access token (~14 days): used by the MCP server to call Webex APIs
• Refresh token (~90 days): used to automatically renew the access token when it expires
• You only need to re-run npm run auth every ~90 days when the refresh token expires

Useful commands:

npm run auth -- --status   # Check token status
npm run auth -- --logout   # Clear stored tokens
npm run auth -- --help     # Full help

5. Configure in your MCP Client

The MCP server needs your Client ID and Client Secret at runtime to automatically refresh expired access tokens. These are passed as environment variables in the MCP configuration.

Why are Client ID / Secret needed here too? The npm run auth step uses them to obtain tokens. The MCP server config needs them to refresh tokens automatically. Without them, you'd have to re-authenticate manually every ~14 days instead of every ~90 days.

VS Code (Copilot / Claude Dev)

Add to your .vscode/mcp.json or VS Code global settings:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json

{
  "mcpServers": {
    "webex-calling": {
      "command": "node",
      "args": ["/Users/<your-username>/Desktop/webex-calling-mcp/dist/index.js"],
      "env": {
        "WEBEX_CLIENT_ID": "your-integration-client-id",
        "WEBEX_CLIENT_SECRET": "your-integration-client-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "webex-calling": {
      "command": "node",
      "args": ["C:\\Users\\<your-username>\\Desktop\\webex-calling-mcp\\dist\\index.js"],
      "env": {
        "WEBEX_CLIENT_ID": "your-integration-client-id",
        "WEBEX_CLIENT_SECRET": "your-integration-client-secret"
      }
    }
  }
}

Security note: This file is local to your machine and not tracked by git. Never commit your credentials.

Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "webex-calling": {
      "command": "node",
      "args": ["/Users/<your-username>/Desktop/webex-calling-mcp/dist/index.js"],
      "env": {
        "WEBEX_CLIENT_ID": "your-integration-client-id",
        "WEBEX_CLIENT_SECRET": "your-integration-client-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "webex-calling": {
      "command": "node",
      "args": ["C:\\Users\\<your-username>\\Desktop\\webex-calling-mcp\\dist\\index.js"],
      "env": {
        "WEBEX_CLIENT_ID": "your-integration-client-id",
        "WEBEX_CLIENT_SECRET": "your-integration-client-secret"
      }
    }
  }
}

6. Start Talking to Your Infrastructure

Once configured, restart VS Code or Claude Desktop, then just ask questions in natural language. The AI will automatically pick the right MCP tools.

Architecture

┌─────────────────┐     stdio / JSON-RPC     ┌──────────────────────┐
│   AI Assistant   │ ◄──────────────────────► │  MCP Server          │
│ (Claude/Copilot) │                          │  (this project)      │
└─────────────────┘                          └──────┬───────────────┘
                                                     │ HTTPS
                                                     ▼
                                              ┌──────────────────────┐
                                              │  Webex REST APIs     │
                                              │  webexapis.com/v1    │
                                              └──────────────────────┘

• Transport: stdio (standard model context protocol)
• SDK: @modelcontextprotocol/sdk (official MCP TypeScript SDK)
• API Client: Typed wrapper around Webex REST API v1
• Auth: OAuth2 Integration (Client ID / Client Secret) with auto-refresh

Project Structure

src/
├── index.ts             # MCP server entry point
├── auth.ts              # OAuth2 authentication (PKCE flow + token refresh)
├── auth-cli.ts          # CLI for login, status, logout
├── webex-api.ts         # Webex REST API client
└── tools/
    ├── people.ts        # People & user management
    ├── call-forwarding.ts # Call forwarding, voicemail, DND, intercept
    ├── hunt-groups.ts   # Hunt group CRUD
    ├── call-queues.ts   # Call queue CRUD
    ├── numbers.ts       # Phone number management
    ├── analytics.ts     # CDR & missed call reports
    ├── locations.ts     # Locations, schedules, auto attendants
    ├── devices.ts       # Devices, workspaces, caller ID
    └── contacts.ts      # Organization contacts & groups

Development

# Run in development mode (no build step)
WEBEX_CLIENT_ID=xxx WEBEX_CLIENT_SECRET=yyy npx tsx src/index.ts

# Build for production
npm run build

# Run production build
WEBEX_CLIENT_ID=xxx WEBEX_CLIENT_SECRET=yyy node dist/index.js

# Set environment variables (do this once per terminal session)
$env:WEBEX_CLIENT_ID="xxx"
$env:WEBEX_CLIENT_SECRET="yyy"

# Run in development mode
npx tsx src/index.ts

# Build for production
npm run build

# Run production build
node dist/index.js

Security Notes

• Never commit your Client ID / Client Secret — always use environment variables
• Tokens are stored locally in ~/.webex-mcp/tokens.json (macOS/Linux) or %USERPROFILE%\.webex-mcp\tokens.json (Windows) with restricted permissions
• Token scope requirements depend on which tools you use:
  • spark-admin:people_read — people listing
  • spark-admin:telephony_config_read / _write — calling config
  • spark-admin:calling_cdr_read — call history/CDR
  • spark-admin:devices_read — device inventory

License

MIT