Digital Samba MCP Server

A Model Context Protocol (MCP) server implementation for Digital Samba's video conferencing API, allowing AI agents like Claude to seamlessly interact with Digital Samba rooms, participants, and meetings.

Installation
Quick Start
Claude Desktop Integration
CLI Usage
API Usage
Features
Configuration
Advanced Usage
Examples
Troubleshooting
License

Installation

Local Installation (Recommended)

npm install digital-samba-mcp-server

Then use with npx:

npx digital-samba-mcp-server --api-key YOUR_API_KEY

Global Installation

While global installation is supported, we recommend local installation for better version management and dependency control.

npm install -g digital-samba-mcp-server
digital-samba-mcp-server --api-key YOUR_API_KEY

Quick Start

Using the CLI

The fastest way to get started is to use the command-line interface with npx:

npx digital-samba-mcp-server --api-key YOUR_DIGITAL_SAMBA_API_KEY

This will start the MCP server on port 3000 and expose resources and tools for Digital Samba's video conferencing functionality.

Using the API

import { startServer } from 'digital-samba-mcp-server';

// Start the server with options
const server = startServer({
  port: 4000,
  apiUrl: 'https://api.digitalsamba.com/api/v1',
  webhookSecret: 'your_webhook_secret',
  publicUrl: 'https://your-server.example.com'
});

Claude Desktop Integration

The Digital Samba MCP Server is designed to work seamlessly with Claude Desktop, enabling Claude to create and manage Digital Samba video conferencing sessions.

Configure Claude Desktop

Start the Digital Samba MCP Server locally:

npx digital-samba-mcp-server --api-key YOUR_DIGITAL_SAMBA_API_KEY

Open Claude Desktop and navigate to Settings > Advanced > MCP Servers:
- Click "Add Server"
- Enter the following information:
  - Name: Digital Samba
  - URL: http://localhost:3000/mcp
  - Add the following header:
    - Name: Authorization
    - Value: Bearer YOUR_DIGITAL_SAMBA_API_KEY
- Click "Save"
Select "Digital Samba" from the MCP server dropdown in Claude Desktop.
You can now ask Claude to interact with Digital Samba:
- "List my Digital Samba rooms"
- "Create a new Digital Samba meeting called 'Team Weekly'"
- "Generate a join link for room XYZ"
- "Show me participants in my active meetings"

Example Claude Prompts

Here are examples of requests you can make to Claude once the Digital Samba MCP server is connected:

List Rooms

Show me all my Digital Samba meeting rooms.

Create Room

Create a new Digital Samba meeting room called "Weekly Team Sync" with a maximum of 20 participants.

Generate Join Link

Generate a join link for my "Weekly Team Sync" room with the name "Meeting Host".

View Participants

Show me who's currently in my Digital Samba meetings.

Schedule Meeting

Schedule a Digital Samba meeting called "Quarterly Review" for next Monday at 10 AM Eastern Time with the following participants: [email list].

CLI Usage

npx digital-samba-mcp-server [options]

Options:
  -p, --port <port>                 Port to run the server on (default: 3000)
  -k, --api-key <key>               Digital Samba API key
  -u, --api-url <url>               Digital Samba API URL (default: https://api.digitalsamba.com/api/v1)
  -l, --log-level <level>           Log level (default: info)
  -w, --webhook-secret <secret>     Secret for webhook verification
  -e, --webhook-endpoint <path>     Webhook endpoint path (default: /webhooks/digitalsamba)
  --public-url <url>                Public URL for the server (for webhook callbacks)
  --enable-rate-limiting            Enable rate limiting for API requests
  --rate-limit-requests-per-minute  Maximum requests per minute per API key (default: 60)
  --enable-cache                    Enable caching of API responses
  --cache-ttl                       Cache Time-To-Live in milliseconds (default: 300000)
  --enable-metrics                  Enable Prometheus metrics collection
  --metrics-endpoint <path>         Path for metrics endpoint (default: /metrics)
  --metrics-prefix <prefix>         Prefix for metrics names (default: digital_samba_mcp_)
  --collect-default-metrics         Collect default Node.js metrics (default: true)
  -h, --help                        Display help message

Environment Variables

All CLI options can also be specified as environment variables:

PORT - Port to run the server on
DIGITAL_SAMBA_API_KEY - Digital Samba API key
DIGITAL_SAMBA_API_URL - Digital Samba API URL
LOG_LEVEL - Log level (error, warn, info, http, verbose, debug, silly)
WEBHOOK_SECRET - Secret for webhook verification
WEBHOOK_ENDPOINT - Webhook endpoint path
PUBLIC_URL - Public URL for the server
ENABLE_RATE_LIMITING - Enable rate limiting (true/false)
RATE_LIMIT_REQUESTS_PER_MINUTE - Maximum requests per minute
ENABLE_CACHE - Enable caching (true/false)
CACHE_TTL - Cache TTL in milliseconds
ENABLE_METRICS - Enable Prometheus metrics collection (true/false)
METRICS_ENDPOINT - Endpoint path for metrics (default: /metrics)
METRICS_PREFIX - Prefix for metrics names (default: digital_samba_mcp_)
COLLECT_DEFAULT_METRICS - Collect default Node.js metrics (true/false)

API Usage

Creating a Server

import { createServer } from 'digital-samba-mcp-server';

const { server, port, apiUrl } = createServer({
  port: 4000,
  apiUrl: 'https://api.digitalsamba.com/api/v1',
  webhookSecret: 'your_webhook_secret',
  webhookEndpoint: '/webhooks/digitalsamba',
  publicUrl: 'https://your-server.example.com'
});

Starting a Server

import { startServer } from 'digital-samba-mcp-server';

const httpServer = startServer({
  port: 4000,
  apiUrl: 'https://api.digitalsamba.com/api/v1'
});

// Later, if needed:
httpServer.close();

Using the Digital Samba API Client Directly

import { DigitalSambaApiClient } from 'digital-samba-mcp-server/client';

const client = new DigitalSambaApiClient(
  'your_api_key',
  'https://api.digitalsamba.com/api/v1'
);

// List rooms
const { data: rooms } = await client.listRooms();

// Create a room
const room = await client.createRoom({
  name: 'My Meeting Room',
  privacy: 'private'
});

// Generate a room token
const token = await client.generateRoomToken(room.id, {
  u: 'User Name'
});

console.log('Join URL:', token.link);

Features

The Digital Samba MCP Server provides the following functionality:

Performance Optimization

Rate Limiting: Configurable API request rate limiting to prevent abuse and ensure fair usage
Response Caching: Memory-based caching of API responses for improved performance
Metrics Collection: Prometheus-compatible metrics for monitoring server performance and usage

Room Management

List, create, update, and delete rooms
Generate room tokens for participant access
Manage room settings and participant permissions

Meeting Scheduling

Schedule, update, and cancel meetings
Manage meeting participants
Find available meeting times
Generate meeting join links

Recording Functionality

Start and stop room recordings
List and access recordings
Manage recording settings

Moderation Tools

Mute/unmute participants
Ban/unban participants
Lock/unlock rooms
Manage media settings

Breakout Rooms

Create and manage breakout rooms
Assign participants to breakout rooms
Broadcast messages to breakout rooms

Webhook Integration

Register webhooks to receive event notifications
Listen for room, participant, and recording events
Secure webhook verification with signatures

Configuration

Server Options

The createServer and startServer functions accept the following options:

Option	Type	Description	Default
`port`	number	Port to run the server on	3000
`apiUrl`	string	Digital Samba API URL	https://api.digitalsamba.com/api/v1
`webhookSecret`	string	Secret for webhook verification	undefined
`webhookEndpoint`	string	Webhook endpoint path	/webhooks/digitalsamba
`publicUrl`	string	Public URL for the server	http://localhost:{port}
`enableRateLimiting`	boolean	Enable API request rate limiting	false
`rateLimitRequestsPerMinute`	number	Maximum requests per minute per API key	60
`enableCache`	boolean	Enable API response caching	false
`cacheTtl`	number	Cache Time-To-Live in milliseconds	300000 (5 minutes)
`enableMetrics`	boolean	Enable Prometheus metrics collection	false
`metricsEndpoint`	string	Endpoint for exposing metrics	/metrics
`metricsPrefix`	string	Prefix for metrics names	digital_samba_mcp_
`collectDefaultMetrics`	boolean	Collect default Node.js metrics	true

API Client Options

The DigitalSambaApiClient constructor takes the following parameters:

Parameter	Type	Description	Default
`apiKey`	string	Digital Samba API key	undefined
`apiUrl`	string	Digital Samba API URL	https://api.digitalsamba.com/api/v1

Available MCP Resources and Tools

The Digital Samba MCP Server exposes the following resources and tools to MCP clients like Claude Desktop:

Resources

Resource URI	Description
`digitalsamba://rooms`	List all rooms
`digitalsamba://rooms/{roomId}`	Get details for a specific room
`digitalsamba://rooms/{roomId}/participants`	List participants in a room
`digitalsamba://recordings`	List all recordings
`digitalsamba://recordings/{recordingId}`	Get details for a specific recording
`digitalsamba://webhooks`	List all registered webhooks
`digitalsamba://meetings`	List all scheduled meetings
`digitalsamba://meetings/{meetingId}`	Get details for a specific meeting

Tools

Tool Name	Description
`create-room`	Create a new room
`update-room`	Update an existing room
`delete-room`	Delete a room
`generate-token`	Generate a token for room access
`register-webhook`	Register a webhook for events
`delete-webhook`	Delete a registered webhook
`list-webhooks`	List all registered webhooks
`list-webhook-events`	List available webhook event types
`start-recording`	Start recording in a room
`stop-recording`	Stop recording in a room
`delete-recording`	Delete a recording
`ban-participant`	Ban a participant from a room
`unban-participant`	Unban a participant from a room
`mute-participant`	Mute a participant
`create-breakout-rooms`	Create breakout rooms for a parent room
`assign-participants`	Assign participants to breakout rooms
`broadcast-message`	Broadcast a message to all breakout rooms
`create-meeting`	Schedule a new meeting
`update-meeting`	Update a scheduled meeting
`cancel-meeting`	Cancel a scheduled meeting
`add-participants`	Add participants to a meeting

Advanced Usage

Metrics Collection with Prometheus

The Digital Samba MCP Server includes built-in support for Prometheus metrics, which allows you to monitor server performance, API calls, caching, and more.

Enabling Metrics

Metrics can be enabled via CLI arguments:

npx digital-samba-mcp-server --enable-metrics --metrics-endpoint /metrics --metrics-prefix digital_samba_mcp_

Or via environment variables:

ENABLE_METRICS=true METRICS_ENDPOINT=/metrics METRICS_PREFIX=digital_samba_mcp_ npx digital-samba-mcp-server

Or when using the API:

import { startServer } from 'digital-samba-mcp-server';

const server = startServer({
  enableMetrics: true,
  metricsEndpoint: '/metrics',
  metricsPrefix: 'digital_samba_mcp_',
  collectDefaultMetrics: true
});

Available Metrics

The server exposes the following metrics:

HTTP metrics (request counts, duration, response sizes)
API client metrics (requests, errors, latency)
Cache metrics (hits, misses, size)
Rate limiting metrics
Connection metrics (active sessions, connections)
Default Node.js metrics (memory, CPU, etc.)

Setting Up Prometheus

For detailed instructions on setting up Prometheus to scrape metrics from the Digital Samba MCP Server, see the Prometheus Setup Guide.

A sample Grafana dashboard is also available in the docs/grafana-dashboard.json file.

Custom Error Handling

The package includes standardized error types that can be used for consistent error handling:

import { 
  DigitalSambaError, 
  AuthenticationError,
  ResourceNotFoundError
} from 'digital-samba-mcp-server/server';

try {
  // Some operation that might fail
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Authentication failed:', error.message);
  } else if (error instanceof ResourceNotFoundError) {
    console.log(`Resource not found: ${error.resourceType} with ID ${error.resourceId}`);
  } else if (error instanceof DigitalSambaError) {
    console.log('Digital Samba error:', error.message);
  } else {
    console.log('Unknown error:', error);
  }
}

Webhook Handling

import express from 'express';
import { WebhookService, setupWebhookTools } from 'digital-samba-mcp-server/server';

const app = express();
app.use(express.json());

const webhookService = new WebhookService(mcpServer, {
  secret: 'your_webhook_secret',
  endpoint: '/webhooks/digitalsamba'
});

// Register webhooks
webhookService.registerWebhookEndpoint(app);

// Register custom event handlers
webhookService.on('room.created', async (payload) => {
  console.log('Room created:', payload.data.id);
});

webhookService.on('participant.joined', async (payload) => {
  console.log('Participant joined:', payload.data.name);
});

Advanced Configuration with Rate Limiting and Caching

import { startServer } from 'digital-samba-mcp-server';

// Start the server with advanced configuration
const server = startServer({
  port: 4000,
  apiUrl: 'https://api.digitalsamba.com/api/v1',
  // Enable rate limiting
  enableRateLimiting: true,
  rateLimitRequestsPerMinute: 60, // 60 requests per minute per API key
  // Enable response caching
  enableCache: true,
  cacheTtl: 60000, // Cache responses for 1 minute
});

Examples

Creating a Room and Generating Join Links

import { DigitalSambaApiClient } from 'digital-samba-mcp-server/client';

const client = new DigitalSambaApiClient('your_api_key');

async function createMeetingRoom() {
  // Create a room
  const room = await client.createRoom({
    name: 'Team Meeting',
    privacy: 'private',
    max_participants: 10
  });
  console.log(`Room created: ${room.id}`);
  
  // Generate join links for participants
  const hostToken = await client.generateRoomToken(room.id, {
    u: 'Meeting Host',
    role: 'host'
  });
  
  const participantToken = await client.generateRoomToken(room.id, {
    u: 'Team Member'
  });
  
  console.log(`Host link: ${hostToken.link}`);
  console.log(`Participant link: ${participantToken.link}`);
}

createMeetingRoom().catch(console.error);

Scheduling a Meeting

import { DigitalSambaApiClient } from 'digital-samba-mcp-server/client';

const client = new DigitalSambaApiClient('your_api_key');

async function scheduleMeeting() {
  const meeting = await client.createScheduledMeeting({
    title: 'Weekly Team Sync',
    description: 'Weekly sync meeting to discuss ongoing projects',
    start_time: '2025-06-01T14:00:00Z',
    end_time: '2025-06-01T15:00:00Z',
    timezone: 'UTC',
    host_name: 'Team Lead',
    host_email: 'team.lead@example.com',
    participants: [
      { name: 'Alice', email: 'alice@example.com' },
      { name: 'Bob', email: 'bob@example.com' }
    ],
    recurring: true,
    recurrence_pattern: 'FREQ=WEEKLY;BYDAY=MO',
    send_invitations: true
  });
  
  console.log(`Meeting scheduled: ${meeting.id}`);
  console.log(`Starts: ${new Date(meeting.start_time).toLocaleString()}`);
}

scheduleMeeting().catch(console.error);

Testing with MCP Inspector

You can test the Digital Samba MCP Server using the MCP Inspector tool:

Install the MCP Inspector:

npm install -g @modelcontextprotocol/inspector

Start the Digital Samba MCP Server:

npx digital-samba-mcp-server --api-key YOUR_DIGITAL_SAMBA_API_KEY

Run the MCP Inspector:

mcp-inspector --url http://localhost:3000/mcp --header "Authorization: Bearer YOUR_DIGITAL_SAMBA_API_KEY"

The MCP Inspector will allow you to:
- Browse available resources and tools
- Try out tool calls
- Explore resource URIs
- Verify MCP protocol compliance

Local Development Testing

If you're developing the Digital Samba MCP package locally and want to test it without publishing to npm, you can use the following methods:

Method 1: Using npm link

This method creates a global link to your local package:

# In the digital-samba-mcp-server directory
npm run build:clean  # Build the package first
npm link

# Now you can use it from anywhere
npx digital-samba-mcp-server YOUR_API_KEY

For Windows users, you can use the included script:

link-local-test.bat

Method 2: Using Local Test Scripts

The package includes scripts for testing locally:

# In the digital-samba-mcp-server directory
test-local-npm.bat YOUR_API_KEY

Or with additional options:

test-local-npm.bat YOUR_API_KEY --port 4000 --log-level debug

Method 3: Direct Integration with Claude Desktop

For optimal Claude Desktop integration, use the dedicated Windows batch file wrapper:

"Digital_Samba": {
  "command": "C:\\path\\to\\digital-samba-mcp-server\\claude-desktop-wrapper.bat",
  "args": ["YOUR_API_KEY"]
}

Using a .bat file avoids Windows "Open with" prompts since Windows knows how to execute batch files natively.

The batch file wrapper:

Redirects log output to a file for debugging (claude-desktop.log)
Sets up proper environment variables for JSON-RPC communication
Logs startup information for troubleshooting

Add this configuration to Claude Desktop's MCP Server setup.

Troubleshooting

For common issues and solutions, please see the TROUBLESHOOTING.md file.

Common Issues

Authentication Errors
- Make sure you're using a valid Digital Samba API key
- Ensure the Authorization header is formatted correctly: Bearer YOUR_API_KEY
Connection Issues
- Verify the server is running on the expected port
- Check firewall settings if connecting remotely
- Ensure the MCP client is using the correct URL
Rate Limiting
- If you encounter 429 Too Many Requests errors, you may be exceeding the rate limit
- Enable rate limiting with a higher threshold or add caching to reduce API calls

License

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