create-mcp-server

KO | EN

gitlite — search

#git #framework #generative-ai #containers #typescript #privacy #macos #automation #docker #cli

create-mcp-server

(★ 17)

Scaffold a lean, best-practice MCP server that passes the quality checks by construction, with tests, CI and docs built in.

File Explorer

ZIP Download

- __init__.py
- __main__.py
- cli.py
- scaffold.py
- templates.py
- __init__.py
- test_scaffold.py
.gitignore
LICENSE
pyproject.toml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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.

create-mcp-server

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

create-mcp-server

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README