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

$3

``bash
npx osc-mcp-server
`

$3

`bash
npm install -g osc-mcp-server
osc-mcp-server
`

$3

`bash
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

$3

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:

`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

$3

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:
`json
{
"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:
`json
{
"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:
`json
{
"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:
`json
{
"endpointId": "endpoint_8000_1234567890"
}
`

$3

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

`bash

Start the server

npx osc-mcp-server

The server will output startup information to stderr

and handle MCP communication via stdin/stdout

`

$3

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

1. Create an endpoint to listen for OSC messages:
`json
{
"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:
`json
{
"tool": "get_osc_messages",
"parameters": {
"timeWindowSeconds": 60,
"limit": 100
}
}
`

4. Check endpoint status:
`json
{
"tool": "get_endpoint_status",
"parameters": {}
}
`

5. Stop the endpoint when done:
`json
{
"tool": "stop_osc_endpoint",
"parameters": {
"endpointId": "endpoint_8000_1234567890"
}
}
`

Development

`bash

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

$3

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

$3

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

$3

#### Firewall Settings

Windows:
`cmd

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:
`bash

Check if firewall is blocking the port

sudo pfctl -sr | grep 8000
`

Linux (Ubuntu/Debian):
`bash

Allow UDP traffic on port 8000

sudo ufw allow 8000/udp
`

#### Testing OSC Communication

Use these tools to test OSC message sending:

SuperCollider:
`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):
`python
from pythonosc import udp_client

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

$3

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

`bash
npx osc-mcp-server 2> debug.log
`

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

$3

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

$3

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

$3

- 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

$3

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

$3

- 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

$3

Create a new release by pushing a git tag:

`bash
git tag v1.0.0
git push origin v1.0.0
`

Or use the PowerShell release script:

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

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

License

MIT