OSC MCP Server

A Model Context Protocol (MCP) server that enables AI agents to create OSC (Open Sound Control) endpoints and receive OSC messages. This server provides a bridge between AI agents and OSC-enabled applications like SuperCollider, Max/MSP, TouchOSC, and other music/audio software.

Features

• OSC Endpoint Management: Create and manage multiple UDP endpoints for receiving OSC messages
• Message Buffering: Store and query received OSC messages with configurable buffer sizes
• Pattern Filtering: Filter messages by OSC address patterns for targeted data collection
• VSCode Integration: Full compatibility with VSCode's MCP client for seamless development workflow
• Real-time Monitoring: Track endpoint status and message flow in real-time
• Type Safety: Built with TypeScript for robust type checking and better developer experience

Installation

Quick Start with npx (Recommended)

npx osc-mcp-server

Global Installation

npm install -g osc-mcp-server
osc-mcp-server

Local Installation

npm install osc-mcp-server
npx osc-mcp-server

Requirements

• Node.js: 18.0.0 or higher
• Operating System: Windows, macOS, or Linux
• Network: UDP port access for OSC communication (ports 1024-65535)

Usage

VSCode Integration

The OSC MCP Server is designed to work seamlessly with VSCode's MCP client. To configure it:

1. Install the MCP extension in VSCode (if not already installed)

2. Add server configuration to your VSCode settings or workspace .vscode/settings.json:

{
  "mcp.servers": {
    "osc-server": {
      "command": "npx",
      "args": ["osc-mcp-server"],
      "env": {}
    }
  }
}

3. Restart VSCode to load the server

4. Verify connection by checking the MCP panel in VSCode - you should see "osc-server" listed as active

Available Tools

The server provides four main tools for OSC interaction:

1. create_osc_endpoint

Creates a new OSC endpoint to listen for incoming messages.

Parameters:

• port (required): UDP port number (1024-65535)
• bufferSize (optional): Maximum messages to store (default: 1000, max: 10000)
• addressFilters (optional): Array of OSC address patterns to filter messages

Example:

{
  "port": 8000,
  "bufferSize": 500,
  "addressFilters": ["/synth/*", "/effects/reverb"]
}

2. stop_osc_endpoint

Stops and removes an existing OSC endpoint.

Parameters:

• endpointId (required): ID of the endpoint to stop

Example:

{
  "endpointId": "endpoint_8000_1234567890"
}

3. get_osc_messages

Queries received OSC messages from endpoints.

Parameters:

• endpointId (optional): Specific endpoint ID (if omitted, queries all endpoints)
• addressPattern (optional): OSC address pattern to filter messages
• timeWindowSeconds (optional): Time window in seconds (from now backwards)
• limit (optional): Maximum number of messages to return (max: 1000)

Example:

{
  "endpointId": "endpoint_8000_1234567890",
  "addressPattern": "/synth/freq",
  "timeWindowSeconds": 30,
  "limit": 50
}

4. get_endpoint_status

Gets status information for OSC endpoints.

Parameters:

• endpointId (optional): Specific endpoint ID (if omitted, returns all endpoints)

Example:

{
  "endpointId": "endpoint_8000_1234567890"
}

Command Line Usage

When running the server directly, it starts in stdio mode for MCP communication:

# Start the server
npx osc-mcp-server

# The server will output startup information to stderr
# and handle MCP communication via stdin/stdout

Example Workflow

Here's a typical workflow for using the OSC MCP Server:

1. Create an endpoint to listen for OSC messages:

   {
     "tool": "create_osc_endpoint",
     "parameters": {
       "port": 8000,
       "bufferSize": 1000,
       "addressFilters": ["/synth/*"]
     }
   }

2. Send OSC messages from your application (SuperCollider, Max/MSP, etc.) to localhost:8000

3. Query received messages:

   {
     "tool": "get_osc_messages",
     "parameters": {
       "timeWindowSeconds": 60,
       "limit": 100
     }
   }

4. Check endpoint status:

   {
     "tool": "get_endpoint_status",
     "parameters": {}
   }

5. Stop the endpoint when done:

   {
     "tool": "stop_osc_endpoint",
     "parameters": {
       "endpointId": "endpoint_8000_1234567890"
     }
   }

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

Troubleshooting

Common Issues

Server Connection Issues

Problem: VSCode shows "osc-server" as disconnected or not listed

• Solution: Check that Node.js 18+ is installed and accessible
• Solution: Verify the MCP configuration in VSCode settings
• Solution: Restart VSCode after configuration changes
• Solution: Check VSCode's output panel for MCP-related error messages

Problem: "Command not found" error when using npx

• Solution: Ensure npm is installed and up to date: npm install -g npm@latest
• Solution: Clear npm cache: npm cache clean --force
• Solution: Try installing globally first: npm install -g osc-mcp-server

OSC Endpoint Issues

Problem: "Port already in use" error

• Solution: Choose a different port number (1024-65535)
• Solution: Check what's using the port: netstat -an | grep :8000 (replace 8000 with your port)
• Solution: Stop other applications using the same port

Problem: "Permission denied" error on low port numbers

• Solution: Use ports 1024 and above (ports below 1024 require admin privileges)
• Solution: On Linux/macOS, run with sudo only if absolutely necessary

Problem: No OSC messages received

• Solution: Verify the sending application is configured to send to the correct IP and port
• Solution: Check firewall settings - ensure UDP traffic is allowed on the specified port
• Solution: Test with a simple OSC sender like TouchOSC or SuperCollider
• Solution: Verify address filters aren't too restrictive

Message Query Issues

Problem: Empty message results when messages should exist

• Solution: Check the time window - messages might be older than the specified timeWindowSeconds
• Solution: Verify address pattern matching - OSC patterns are case-sensitive
• Solution: Check if endpoint buffer size was exceeded (older messages get removed)

Problem: "Endpoint not found" error

• Solution: Use get_endpoint_status to list available endpoint IDs
• Solution: Verify the endpoint wasn't stopped or crashed
• Solution: Check for typos in the endpoint ID

Performance Considerations

High-Frequency Messages

If you're receiving many OSC messages per second:

• Increase buffer size to prevent message loss: "bufferSize": 5000
• Use address filters to reduce processing overhead
• Query messages more frequently to prevent buffer overflow
• Consider multiple endpoints for different message types

Memory Usage

• Monitor buffer sizes - larger buffers use more memory
• Set appropriate limits on message queries to avoid large responses
• Stop unused endpoints to free resources

Network Configuration

Firewall Settings

Windows:

# Allow UDP traffic on port 8000 (replace with your port)
netsh advfirewall firewall add rule name="OSC MCP Server" dir=in action=allow protocol=UDP localport=8000

macOS:

# Check if firewall is blocking the port
sudo pfctl -sr | grep 8000

Linux (Ubuntu/Debian):

# Allow UDP traffic on port 8000
sudo ufw allow 8000/udp

Testing OSC Communication

Use these tools to test OSC message sending:

SuperCollider:

// Send a test message
n = NetAddr("127.0.0.1", 8000);
n.sendMsg("/test", 440, "hello");

Max/MSP:

[udpsend 127.0.0.1 8000]
|
[/test 440 hello(

Python (python-osc):

from pythonosc import udp_client

client = udp_client.SimpleUDPClient("127.0.0.1", 8000)
client.send_message("/test", [440, "hello"])

Debug Mode

For detailed logging, you can check the stderr output when running the server:

npx osc-mcp-server 2> debug.log

This will capture all debug messages to a file for analysis.

Getting Help

If you encounter issues not covered here:

1. Check the GitHub Issues: https://github.com/username/osc-mcp-server/issues
2. Create a new issue with:
   • Your operating system and Node.js version
   • Complete error messages
   • Steps to reproduce the problem
   • Your MCP configuration

Documentation

API Reference

• Complete API Reference - Detailed documentation of all MCP tools and their parameters

Examples and Workflows

• Examples Overview - All available examples and configurations
• VSCode Configuration - VSCode MCP client setup examples
• OSC Senders - Test OSC message senders for various platforms
• Workflow Examples - Step-by-step usage workflows

Specific Workflows

• Basic Workflow - Getting started with a single endpoint
• Multi-Endpoint Workflow - Managing multiple OSC sources

Development

• CI/CD Documentation - Continuous integration and deployment details

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment:

• Automated Testing: Runs on Node.js 18, 20, and 22
• Code Quality: ESLint, Prettier, and TypeScript checks
• Security Scanning: npm audit and vulnerability scanning
• Coverage Reporting: 80% coverage threshold required
• Automated Publishing: Publishes to npm on tagged releases

Release Process

Create a new release by pushing a git tag:

git tag v1.0.0
git push origin v1.0.0

Or use the PowerShell release script:

.\scripts\release.ps1 patch  # or minor, major, prerelease

For detailed CI/CD documentation, see docs/CI-CD.md.

License

MIT