Content
<div align="center">
# 🏗️ MCP Studio
### The Complete Toolkit for Building MCP (Model Context Protocol) Servers
[](LICENSE)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
[](https://github.com/namangoyal3/mcp-studio)
**Scaffold · Develop · Inspect · Deploy** — everything you need to build production-ready MCP servers.
[Getting Started](#-quick-start) • [Documentation](docs/) • [Examples](examples/) • [Contributing](CONTRIBUTING.md)
</div>
---
## 🎯 What is MCP Studio?
**MCP Studio** is an open-source toolkit that makes it effortless to **build, test, and debug** [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers.
> **MCP** is the open standard that lets AI models like Claude connect to your tools, databases, files, and APIs — think of it as a "USB-C port for AI."
MCP Studio gives you:
- ✅ **`mcp-studio init`** — Scaffold a complete MCP server in seconds
- ✅ **`mcp-studio dev`** — Hot-reload development server
- ✅ **`mcp-studio inspect`** — Debug and inspect any MCP server
- ✅ **`mcp-studio build`** — Production build with TypeScript compilation
- ✅ **Web Playground** — Visual UI to test tools interactively
- ✅ **Template System** — Start from `basic` or `tool-server` templates
- ✅ **First-class TypeScript** — Full type safety, strict mode
---
## 📸 Preview
```
┌─ mcp-studio inspect "node dist/index.js" ──────────────────┐
│ │
│ ✔ Server started in 124ms │
│ ✔ Found 3 tool(s): │
│ │
│ greet │
│ Generate a personalized greeting │
│ Arguments: name:string*, style:string │
│ │
│ calculate │
│ Perform arithmetic operations │
│ Arguments: a:number*, b:number*, operation:string* │
│ │
│ fetch_json │
│ Fetch JSON data from a URL │
│ Arguments: url:string* │
│ │
│ ✔ Inspection completed in 89ms │
└─────────────────────────────────────────────────────────────┘
```
---
## 🚀 Quick Start
### 1. Install & Scaffold
```bash
# Clone the repo
git clone https://github.com/namangoyal3/mcp-studio.git
cd mcp-studio
pnpm install && pnpm build
# Create your first MCP server
mcp-studio init my-weather-app
cd my-weather-app
```
### 2. Build & Run
```bash
npm install
npm run build
npm start
```
### 3. Inspect Your Server
In another terminal:
```bash
mcp-studio inspect "node dist/index.js"
```
### 4. Connect to Claude Code
Add to your `~/.claude/servers.json`:
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["path/to/my-server/dist/index.js"]
}
}
}
```
That's it! Your AI tools can now discover and call your tools automatically. 🎉
---
## 🛠️ CLI Commands
| Command | Description | Example |
|---------|-------------|---------|
| `init` | Scaffold a new MCP server | `mcp-studio init my-server -t tool-server` |
| `dev` | Start with hot reload | `mcp-studio dev` |
| `build` | Compile TypeScript | `mcp-studio build --outdir dist` |
| `inspect` | Debug a running server | `mcp-studio inspect "node dist/index.js"` |
### Options
- `init --template basic|tool-server` — Choose template
- `inspect --json` — Output as JSON
- `dev --port 3030` — Custom playground port
- `dev --no-watch` — Disable file watching
---
## 🎨 Web Playground
MCP Studio includes a **beautiful web-based playground** for visually testing your MCP servers:
```bash
cd packages/playground
pnpm dev
```
Opens at `http://localhost:3030` with:
- 🔌 **Connection panel** — Configure and connect to MCP servers
- 🛠️ **Interactive tool cards** — Call tools with custom arguments
- 📋 **Live console** — Real-time log of all activity
- 🔄 **Server status indicator** — Know when you're connected
---
## 📦 Project Structure
```
mcp-studio/
├── packages/
│ ├── core/ # 📚 Core types, server builder, transport
│ ├── cli/ # ⌨️ CLI tool (mcp-studio commands)
│ ├── playground/ # 🎨 Web-based playground (React + Vite)
│ └── templates/ # 📋 Project scaffolding templates
├── examples/
│ ├── weather-mcp/ # 🌤️ Weather data MCP server
│ └── filesystem-mcp/ # 📁 Read-only filesystem MCP server
├── docs/ # 📖 Documentation
└── README.md
```
---
## 🌟 Why MCP Studio?
### For AI Developers 🤖
Build custom tool integrations for Claude Code, Copilot, Cursor, and other MCP-compatible AI tools.
### For TypeScript Developers 💙
Full type safety, strict mode, and first-class TypeScript support throughout.
### For Open Source Contributors 🤝
Clean architecture, well-documented code, and easy onboarding.
---
## 📚 Learn More
- [Getting Started Guide](docs/getting-started.md)
- [Architecture Overview](docs/architecture.md)
- [API Reference](docs/api-reference.md)
- [MCP Specification](https://modelcontextprotocol.io)
- [Example Servers](examples/)
---
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
**Ways to contribute:**
- 🐛 Report bugs via [Issues](https://github.com/namangoyal3/mcp-studio/issues)
- 💡 Suggest features
- 📝 Improve documentation
- 🛠️ Submit pull requests
---
## 📄 License
[MIT](LICENSE) © [Naman Goyal](https://github.com/namangoyal3)
---
<div align="center">
**Built with ❤️ for the MCP ecosystem**
⭐️ **Star this repo** if you found it useful! ⭐️
</div>
