# 🤖 mcp-server

![Last Commit](https://img.shields.io/github/last-commit/reory/mcp-server?cacheSeconds=60)
![Repo Size](https://img.shields.io/github/repo-size/reory/mcp-server?cacheSeconds=60)
![License](https://img.shields.io/badge/License-MIT-green)

![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)
![FastMCP](https://img.shields.io/badge/FastMCP-3.2+-blue?style=for-the-badge&logo=python&logoColor=white)
![Jinja2](https://img.shields.io/badge/jinja-white?style=for-the-badge&logo=jinja&logoColor=black)

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

---
## 📸 Screenshots
![Dashboard MCP Launcher](screenshots/mcp-server.png)
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

```text
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
```bash
git clone [https://github.com/reory/mcp-server.git](https://github.com/reory/mcp-server.git)
cd mcp_gen
```

### Create and activate virtual environment
```bash
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:
```bash
pip install -e .
```

### Verify installation:
```Bash
mcpgen --help
```

---

## 🚀 Usage
- Generate a brand-new MCP server repository anywhere on your filesystem:
```Bash
mcpgen new my_awesome_tool
```
- To specify a custom target output directory:
```Bash
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:
```bash
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:

```json
{
  "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** 🙂
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Roy%20Peters-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/roy-p-74980b382/)