mcpplay 0.1.0

The Python-native playground for MCP servers

mcpplay

The FastAPI /docs experience, for MCP servers.

Documentation • Getting Started • Issues

mcpplay gives you a browser-based playground for any MCP server. One command, and you get auto-generated forms, live results, and a full execution timeline.

Installation

pip install mcpplay
mcpplay demo

Your browser opens to http://localhost:8321. That's it!

Point it at your own server

mcpplay run server.py
mcpplay run --command "node server.js"
mcpplay run --command "uvx my-mcp-server"

Options

mcpplay run server.py --port 9000        # Custom port (default: 8321)
mcpplay run server.py --no-open          # Don't auto-open browser
mcpplay run server.py --no-reload        # Disable hot reload
mcpplay run server.py --env API_KEY=xxx  # Pass env vars to server

Features

• Schema-aware forms - auto-generated from your tool's JSON Schema, with enums, nested objects, arrays, and defaults.
• Live execution - run tools and see structured results instantly.
• Persistent timeline - every call logged with inputs, outputs, and latency. Replay with one click.
• Hot reload - edit your server, mcpplay restarts it. Session and timeline preserved.
• Localhost-only - bound to 127.0.0.1 with Origin validation. No remote exposure.

How It Works

Browser UI  ←→  mcpplay (Python proxy)  ←→  Your MCP Server
  (Svelte)      (uvicorn + WebSocket)        (stdio)

mcpplay spawns your server as a child process, connects via stdio, and proxies everything through a WebSocket to the browser. Executions are logged to a local SQLite database.

Comparison

	mcpplay	MCP Inspector	MCPJam Inspector
Install	pip install	npx (Node required)	Docker
Python native	✅	❌	❌
Form generation	Full JSON Schema	Basic inputs	Basic inputs
Hot reload	✅	❌	❌
Execution timeline	Persistent, replayable	Log	Log

Development

git clone https://github.com/gauthierpiarrette/mcpplay
cd mcpplay

# Python backend
uv sync --dev
uv run pytest

# Frontend (Svelte)
cd frontend
npm install
npm run dev      # Dev server with HMR
npm run build    # Build to src/mcpplay/static/

License

Apache 2.0