Content
# create-mcp-server
Scaffold a lean, **best-practice MCP server** (stdio transport) in one command,
with tests, CI, docs and an `AGENTS.md` already in place.
Most MCP quality tools inspect a server after the fact: they audit it, grade it,
diff it, load-test it. This one works from the other end. It generates a server
that is well-behaved by construction: one-line tool descriptions, tight input
schemas, read-only hints, no third-party dependencies, and a passing test suite.
Point a context or scorecard checker at what it produces and you start at grade A.
Zero third-party dependencies. Pure standard-library Python. MIT licensed.
> Companion to the MCP-quality toolchain (`mcp-context-budget`, `mcp-scorecard`,
> `mcp-server-audit`, `mcp-conformance-kit`, `mcp-surface-diff`, `mcp-load-lab`).
> Those tools grade a server. **This one builds a server that passes.**
## Install
```bash
pip install create-mcp-server
```
Or run from a checkout with no install:
```bash
python -m create_mcp_server --help
```
## Quickstart
```bash
create-mcp-server my-mcp-server
cd my-mcp-server
python -m unittest discover -s tests -v # generated tests pass
python server.py # speaks MCP over stdio
```
That produces:
```
my-mcp-server/
server.py lean stdio MCP server + example tools
README.md how to run, test, and add tools
AGENTS.md house rules for agents/contributors
pyproject.toml packaging + console-script entry
LICENSE MIT
.gitignore
.github/workflows/ci.yml runs the tests on 3.9 / 3.11 / 3.12
tests/test_server.py boots the server, checks the handshake and tools
```
## Choose your starter tools
Four lean example tools are included; pick any subset:
```bash
create-mcp-server weather-bot --tools echo,current_time
create-mcp-server --list-tools
```
| Tool | Description |
|---|---|
| `echo` | Return the given text unchanged. |
| `add` | Add two numbers and return the sum. |
| `current_time` | Return the current UTC time in ISO 8601 format. |
| `word_count` | Count the words in a piece of text. |
Options: `-o/--output DIR`, `--tools`, `--description`, `--author`, `--force`,
`--list-tools`.
## What "best-practice" means here
The generated `server.py` follows the same discipline the quality tools reward:
- **Lean descriptions.** One line per tool, because every description is spent
from the model's context budget on each turn.
- **Tight schemas.** Small, specific input schemas with no speculative fields.
- **Honest annotations.** Read-only tools carry `readOnlyHint`.
- **No dependencies.** Standard library only, so it runs anywhere Python does.
- **A registry pattern.** New tools are one `@tool` decorator away.
Adding a tool:
```python
@tool(
"greet",
"Return a greeting for a name.",
{"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]},
annotations={"readOnlyHint": True},
)
def greet(name):
return "Hello, %s" % name
```
## Closing the loop
The generated server is designed to pass the checkers in this ecosystem. For
example, straight after scaffolding:
```bash
create-mcp-server loop-demo
mcp-context-budget --min-grade A -- python loop-demo/server.py
# Grade: A Score: 100.0/100
```
Build with `create-mcp-server`, keep it honest with `mcp-context-budget`, and
grade the whole thing with `mcp-scorecard`.
## Development
```bash
python -m unittest discover -s tests -v
```
The test suite scaffolds servers into a temp directory, runs them over stdio,
and executes their generated tests, so a green build means the generator
produces working servers end to end.
## Licence
MIT. Contributions welcome.
MCP Store