Create Mcp Server

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

pip install create-mcp-server

Or run from a checkout with no install:

python -m create_mcp_server --help

Quickstart

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:

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:

@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:

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

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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shriramkv
• Source: shriramkv/create-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.