🔧 MCP Scaffolder

A Python MCP server that scaffolds new projects from your terminal — containerized with Docker, wired into Claude Code.

What It Does

Tell Claude Code to create a project. The MCP server scaffolds it instantly:

You: "Create a new Python project called weather-api"

Claude Code: [calls scaffold_project tool]
             ✅ Created weather-api/
                ├── main.py
                ├── requirements.txt
                ├── README.md
                ├── .gitignore
                └── tests/

Supported languages: Python, Node.js, Go

Quick Start

Prerequisites

| Tool | Minimum Version | Check | |------|----------------|-------| | Python | 3.10 | python3 --version | | Docker | Any recent | docker --version | | Claude Code | Latest | claude --version | | Node.js | 20 | node --version |

Claude Code requires an active Claude Pro, Max, or API plan. Install it using the native binary installer — the npm method is deprecated.

Installation

1. Clone the repository

git clone https://github.com/your-username/mcp-scaffolder.git
cd mcp-scaffolder

2. Build the Docker image

docker build -t mcp-scaffolder .

3. Register with Claude Code

claude mcp add scaffolder -- docker run -i --rm mcp-scaffolder

4. Verify the connection

claude mcp list

Then launch Claude Code and type /mcp to confirm 2 tools are available.

Optional: Save generated projects to your host

mkdir -p ~/projects

claude mcp remove scaffolder
claude mcp add scaffolder -- docker run -i --rm \
  -v "$HOME/projects:/app/projects" \
  mcp-scaffolder

Projects will appear in ~/projects/ on your machine.

Usage

Inside Claude Code, use natural language:

Create a new Python project called "data-pipeline"
What project templates are available?
Scaffold a Go service called "auth-service"
Make me a Node project named "webhook-handler"

Available templates

| Language | Files created | Directories | |----------|--------------|-------------| | python | main.py, requirements.txt, README.md, .gitignore | tests/ | | node | index.js, package.json, README.md, .gitignore | — | | go | main.go, go.mod, README.md, .gitignore | cmd/, internal/ |

Development

Run locally (without Docker)

python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]>=1.25,<2"
python server.py

Test with MCP Inspector

npx @modelcontextprotocol/inspector python server.py

Run tests

pip install pytest
pytest tests/ -v

Project structure

mcp-scaffolder/
├── server.py          ← The MCP server
├── Dockerfile         ← Container definition
├── requirements.txt   ← Python dependencies
├── tests/
│   └── test_tools.py  ← Pytest unit tests
├── TECHNICAL_DOC.md   ← Full technical reference
└── README.md          ← This file

Troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | Disconnected in /mcp | Docker daemon not running | Run docker info | | Server drops immediately | print() writing to stdout | Use sys.stderr for all logging | | Tool not found | Registration issue | Re-run claude mcp list | | Files not on host | No volume mount | Re-register with -v flag | | EOF error on start | Missing -i flag | Check your registration command |

Security

What the server does NOT do: make network requests, read host files, execute shell commands, or accept network connections.

Protections built in:

Path traversal blocked: .., /, \ in project names are rejected
Language validated against an allowlist
Docker container isolates from host filesystem by default
Existing directories are never overwritten

Recommendations:

Only mount specific subdirectories you need (never -v /:/mnt/host)
Scope API tokens in any extended tools to minimum permissions
Do not install MCP packages from untrusted sources

See TECHNICAL_DOC.md for the full security model.

Recommendations

Always use sys.stderr for logging. Any stdout output corrupts the JSON-RPC stream.

Pin the MCP SDK below v2. The >=1.25,<2 constraint is intentional — SDK v2 changes the transport layer.

Rebuild the image after code changes. docker build again for code changes to take effect.

Write docstrings as if the LLM is reading them — because it is. FastMCP uses your docstrings to generate the tool schema.

Mount only what you need. Never expose your home directory or system directories to the container.

Resources

License

MIT

MCP Servers