Pd MCP Server

🚀 Pure Data MCP Server

This project integrates Claude AI with Pure Data through the Model Context Protocol (MCP). With this integration, Claude can dynamically create, modify, and control Pure Data patches via natural language processing.

Known Issues

The example patch (example patch.pd) currently does not work properly.

Overview

The system consists of three core components:

1. MCP Server (mcp_server.py): Implements the Model Context Protocol interface for Claude.
2. OSC Daemon (osc_daemon.py): Handles OSC communication with Pure Data.
3. Pure Data Patch (absolute_final_solution.pd): A dynamic patch solution that receives OSC messages.

✨ Features

• Dynamic Object Creation: Create any Pure Data object on-demand via Claude.
• Connection Management: Connect objects together to build complex signal flows.
• DSP Control: Remotely start and stop audio processing.
• Parameter Control: Modify object parameters in real-time.
• Global Object Tracking: A reliable index-based connection system.
• Error Handling: Robust error detection and reporting.
• Debugging Tools: A comprehensive logging system.

Recent Updates

📦 Installation

Prerequisites

• Python 3.7+
• Pure Data (native) 0.51+
• Required Python packages:
  • python-osc
  • fastmcp
  • jsonschema
• uv Package Manager

Install uv

On macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Learn more: astral-sh/uv

💻 Usage Examples

Clone the Repository

git clone https://github.com/nikmaniatis/Pd-MCP-Server.git

Integrate with Claude Desktop

1. Open:

Claude > Settings > Developers > Edit Configuration > claude_desktop_config.json

2. Add the following code block:

{
    "mcpServers": {
      "Pure Data MCP Server": {
        "command": "uv",
        "args": [
          "--directory",
          "PATH_TO_PD_MCP_SERVER",
          "run",
          "main.py"
        ],
        "env": {
          "PD_OSC_HOST": "127.0.0.1",
          "PD_OSC_PORT": "5000",
          "PD_FEEDBACK_PORT": "5001"
        }
      }
    }
  }

⚠️ Important Note

If the uv command is not found, run which uv (Unix) or Get-Command uv (PowerShell) and use the full path in the "command" field.

🔧 Technical Details

Message Flow

1. Claude executes the MCP tool based on user requests.
2. The MCP server processes the tool calls.
3. Format OSC messages and send them to Pure Data.
4. Pure Data executes commands through the dynamic patch.
5. Feedback (if any) is returned via OSC callback.

Troubleshooting

Common Issues

1. Object creation fails: Ensure that Pure Data is running and the patch is open.
2. Connection issues: Verify that the object ID exactly matches what is returned by create_object.
3. Port conflicts: Check if port 5000 is already in use.
4. Message format errors: Ensure that the message format matches what is expected in the Pure Data patch.
5. Missing objects: If object tracking is confused, restart the MCP server and Pure Data.

JSON Schema

pd-schema.json provides a comprehensive data model for Pure Data patches, supporting patch validation and serialization. Although not used in the current MCP tool, it is a key protocol for implementing AI tools.

📄 License

• Pure Data - An open-source visual programming language.
• Model Context Protocol - A protocol enabling AI tools.
• Python-OSC - An OSC implementation in Python.