🤖 mcp-server

A lightweight CLI tool designed to instantly scaffold and generate production-ready Model Context Protocol (MCP) server projects using FastMCP and Jinja2 templates.

---

📸 Screenshots

The MCP Inspector launches pre-configured to attach to server.py via STDIO. Once connected, it provides live tool testing, payload logs, and server notifications in real time.

---

🌟 Overview

mcpgen streamlines the setup of new MCP servers. Instead of manually writing low-level protocol boilerplate, handling standard input/output streams, or copying setup files across folders, mcpgen generates a complete, isolated server repository in a single command.

---

📋 Prerequisites

Before installing mcpgen, make sure you have:

• Python 3.10+
• Node.js & npm (Required by FastMCP to run @modelcontextprotocol/inspector during testing)

---

📁 Project Structure

mcp_gen/
├── mcpgen/
│   ├── templates/
│   │   ├── mcp.json.j2
│   │   ├── README.md.j2
│   │   ├── requirements.txt.j2
│   │   └── server.py.j2
│   ├── __init__.py
│   ├── cli.py
│   └── generator.py
├── .gitignore
├── pyproject.toml
├── README.md
└── requirements.txt

---

⚒️ Installation & Setup

Clone & Setup Environment

git clone [https://github.com/reory/mcp-server.git](https://github.com/reory/mcp-server.git)
cd mcp_gen

Create and activate virtual environment

python -m venv .venv # .venv\Scripts\activate (Windows)
source .venv/bin/activate  # macOS / Linux

Install in Editable mode

• Install mcpgen locally in editable mode so changes to the source code take effect immediately:

pip install -e .

Verify installation:

mcpgen --help

---

🚀 Usage

• Generate a brand-new MCP server repository anywhere on your filesystem:

mcpgen new my_awesome_tool

• To specify a custom target output directory:

mcpgen new my_awesome_tool --output ./projects

What gets generated?

• Inside the created folder (my_awesome_tool/), you will find:

• server.py — Pre-configured FastMCP server entry point.

• mcp.json — Server metadata configuration.

• requirements.txt — Minimal dependencies (fastmcp, python-dotenv).

• README.md — Starter documentation for your generated server.

Testing generated servers

Navigate into your newly generated server folder and launch the interactive web inspector:

cd my_awesome_tool
fastmcp dev inspector server.py

• This spins up the official MCP Inspector web UI at http://localhost:6274, letting you test tools, view schemas, and debug responses live in your browser.

Note: To run the server without the web UI, use fastmcp run server.py.

---

🔌 Connecting a Generated Server to Claude Desktop

Once you create a server with mcpgen and install its dependencies, register it with Claude Desktop:

• Open your claude_desktop_config.json:

• Windows Store (MSIX): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

---

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

---

Add your server path:

{
  "mcpServers": {
    "my_awesome_tool": {
      "command": "C:\\Path\\To\\Your\\Environment\\Scripts\\python.exe",
      "args": ["C:\\Path\\To\\my_awesome_tool\\server.py"]
    }
  }
}

• ⚠️ Windows Path Tip: Always double up backslashes (\) in JSON file paths to avoid string escape issues.

---

🛣️ Roadmap Features

• Interactive CLI Templates: Prompts for scaffolding custom starter templates (SQLite persistent memory, Web scrapers, Local file system I/O).
• Automated Claude Desktop Registration: Single-command config injection via mcpgen register to link servers to claude_desktop_config.json.
• Multi-Transport Support: Easy switching between stdio (local desktop) and SSE (server-sent events for cloud/web deployment).
• Containerization & Docker Scaffolding: Optional --docker flag to auto-generate Dockerfile and docker-compose.yml for isolated execution.
• OpenAPI / Swagger Conversion: Import existing REST API specs (mcpgen import openapi.json) to auto-generate FastMCP tool signatures.
• Built-in Dev & Inspector Pipeline: mcpgen dev shortcut to launch the official MCP Inspector web UI for immediate protocol debugging.
• Environment & Secret Management: Interactive setup for secret keys (.env creation, python-dotenv integration, and environment variable validation).
• Automated Testing & CI/CD Boilerplate: Scaffolding pre-configured pytest suites and GitHub Actions workflows for continuous integration.

---

• Rust Features

• Rust-Powered Native Extensions (PyO3): Scaffolding option for PyO3 dynamic library extensions to run performance-critical tasks (video processing, heavy math, parsing) in compiled Rust.
• Zero-Dependency CLI Binary: Standalone Rust-compiled mcpgen executable for running generation commands anywhere without needing a Python runtime environment.
• Multi-Language Server Scaffolding (--lang rust): Flag to scaffold native Rust MCP servers using the Rust MCP SDK for ultra-low memory footprint (~5MB) and instant startup.
• High-Concurrency Transport Gateway: Lightweight Rust proxy sidecar to handle external SSE/WebSocket web connections and pipe them seamlessly to local STDIO servers.

---

• Built by Roy Peters 🙂