mcpplay

mcpplay provides a browser-based playground for MCP-compliant servers. It automatically generates a UI from your server's JSON Schema, lets you execute tools, and logs a persistent timeline of inputs, outputs, and latency. You can point mcpplay at an existing MCP server implementation, run a local Python-based server, or use the included demo tooling to explore the UI features. The frontend renders forms from your server's schema and immediately shows results, enabling rapid iteration and debugging of MCP tooling workflows.

To use it, install mcpplay and run the provided command to start the server, then open the local UI in your browser. You can run with the default port or override it with the --port option. The tool supports passing environment variables to your server and hot-reloading during development. You can also point mcpplay at your own Python script or other MCP-compliant backends by specifying the appropriate run command (e.g., python -m mcpplay run server.py).

Prerequisites:

• Python 3.8+ installed on your system
• Internet access to install Python packages

Installation steps:

1. Create and activate a Python virtual environment (optional but recommended)
   • python -m venv venv
   • source venv/bin/activate # on Unix/macOS
   • venv\Scripts\activate # on Windows
2. Install mcpplay from PyPI
   • pip install mcpplay
3. Run mcpplay with your MCP server (demo example)
   • mcpplay run server.py
   • This will start the UI at http://localhost:8321 by default
4. Access the UI in your browser and begin exploring or replace server.py with your own MCP server entrypoint

If you want to run a different backend, adjust the command accordingly (e.g., configure the mcpplay CLI to run your Python module or script).

Tips and common issues:

• Default UI port is 8321; override with --port when starting the CLI (e.g., mcpplay run server.py --port 9000).
• The UI auto-reloads in development mode; hot-reload helps preserve session data and the timeline.
• You can pass environment variables to your MCP server using --env VAR=VALUE (e.g., --env API_KEY=xxx).
• Ensure your MCP server is JSON Schema compliant to maximize form generation and validation in the UI.
• If you encounter CORS or Origin validation issues, run the server locally on localhost and confirm the Origin policy matches your development environment.
• For contributors, the Python backend (uv) and frontend (Svelte) can be developed separately; follow the repository’s Development section for details.