python-starter MCP server
Commit Nov 10, 2026Provides a production-ready template for building Model Context Protocol servers in Python with built-in testing, logging, and deployment configurations.
Also known as BonnieDooneConsulting/mcp-server-python-starter
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is python-starter MCP?
python-starter provides a production-ready template for building Model Context Protocol servers in Python with built-in testing, logging, and deployment configurations.
Summary generated from the project's README
About python-starter MCP server
Developers looking to build production-ready Model Context Protocol servers in Python can use this template to move beyond simple demonstrations. It provides a structured foundation including built-in testing, logging, and deployment configurations. The starter uses the official mcp Python SDK and supports both stdio transport for local clients like Claude Desktop and Claude Code, as well as streamable HTTP for running as a remote service.
This template includes practical examples such as a search_docs tool for paginated lookups and a draft_support_ticket tool that utilizes Pydantic models for input validation. It features JSON logging to stderr to avoid interfering with the stdio protocol channel and includes a Dockerfile for containerized deployment. Users can configure the server using environment variables starting with MCP_STARTER_ or via command line flags. The project is designed for reliability, incorporating Ruff for linting, Pyright for strict type checking, and a suite of tests that run through GitHub Actions.
What you can do with it
- 1Create a searchable documentation toolA developer can implement a read-only lookup tool that allows an AI to query a specific dataset using pagination.
- 2Implement validated data entryYou can build tools that require structured input, ensuring the AI provides valid data before your logic executes.
- 3Deploy an MCP server as a web serviceInstead of running locally, you can host your server using the HTTP transport to make it accessible over a network.
- 4Automate server testing and lintingUse the included testing framework to verify your server logic through in-memory clients and smoke tests.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebonniedooneconsulting/mcp-server-python-starter is public and reachablegithub.com/bonniedooneconsulting/mcp-server-python-starter ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/bonniedooneconsulting/mcp-server-python-starter ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP Server Python Starter
A clean starting point for building your own MCP server in Python. Clone it, swap the example tools for yours, and you've got something you can actually ship.
What this is
MCP (the Model Context Protocol) is an open standard that lets AI apps like Claude call your code, so the model can look up your data or take actions in your systems. An MCP server is the small program that exposes those capabilities, and this repo is a template for writing one well.
If you're new to the idea, I wrote a plain-English intro: What is an MCP server?
I put this together because most MCP examples stop at "hello world." That's fine for a demo. But the first time you put one in front of a real team, you need config, logging that doesn't break stdio, input validation, tests, and a way to deploy it. That's what's here.
What's included
- The official
mcpPython SDK (v2), usingMCPServer. That's the decorator-based API that used to be calledFastMCP. - Two example tools.
search_docsis a read-only lookup with pagination over a small bundled dataset.draft_support_tickettakes a pydantic model as input, so bad input gets a clear error before your code even runs. - A resource template,
docs://{slug}, that returns a doc as Markdown. - A prompt template,
explain_doc, that shows up as a reusable prompt in clients that support them. - Config from environment variables with pydantic-settings (
MCP_STARTER_*, or a.envfile). - JSON logs to stderr. With the stdio transport, stdout is the protocol channel, so one stray
print()can break the connection. Ruff'sT20rule is turned on to catch those. - Two transports: stdio (the default, for local clients) and streamable HTTP (for running it as a service).
- Tests that talk to the server through the SDK's in-memory client, plus a smoke test that launches it over real stdio.
- Ruff, Pyright in strict mode, GitHub Actions CI, and a slim Dockerfile that runs as a non-root user.
The sample data is a made-up help center for a made-up product. It's only there so the tools have something to search. There are no network calls and no secrets.
Quick start
You'll need uv and Python 3.11 or newer.
git clone https://github.com/BonnieDooneConsulting/mcp-server-python-starter.git
cd mcp-server-python-starter
uv sync
Run it over stdio (this is what Claude Code and Claude Desktop use):
uv run mcp-starter
It'll sit there waiting for a client on stdin. That's expected. Press Ctrl+C to stop it.
Or run it over HTTP:
uv run mcp-starter --transport streamable-http --port 8000
# the MCP endpoint is http://127.0.0.1:8000/mcp
Want to poke at it in a browser first? The MCP Inspector is handy for that:
npx @modelcontextprotocol/inspector uv run mcp-starter
Configuration
Every setting can come from a flag, an environment variable, or a .env file. Flags win.
| Variable | Flag | Default |
|---|---|---|
MCP_STARTER_TRANSPORT |
--transport |
stdio |
MCP_STARTER_HOST |
--host |
127.0.0.1 |
MCP_STARTER_PORT |
--port |
8000 |
MCP_STARTER_HTTP_PATH |
/mcp |
|
MCP_STARTER_LOG_LEVEL |
--log-level |
INFO |
MCP_STARTER_LOG_FORMAT |
json (or text) |
|
MCP_STARTER_SERVER_NAME |
mcp-starter |
Connecting to Claude Code
Point Claude Code at your checkout:
claude mcp add mcp-starter -- uv --directory /absolute/path/to/mcp-server-python-starter run mcp-starter
If you're running the HTTP transport instead:
claude mcp add --transport http mcp-starter http://127.0.0.1:8000/mcp
Run claude mcp list to check that it connected, then ask Claude something like "search the help docs for webhooks."
Connecting to Claude Desktop
Open Settings, go to Developer, and click Edit Config. That opens claude_desktop_config.json. Add this:
{
"mcpServers": {
"mcp-starter": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-server-python-starter",
"run",
"mcp-starter"
]
}
}
}
Restart Claude Desktop. If it can't find uv, use the full path from which uv as the command. The desktop app doesn't always see the same PATH your terminal does, and it's a common reason a server shows up as failed.
Adding your own tool
Tools live in src/mcp_starter/tools.py, inside register(). Type hints become the input schema, the docstring becomes the description the model reads, and a pydantic return type becomes structured output. Here's a small one:
from typing import Annotated
from pydantic import BaseModel, Field
class WordCount(BaseModel):
words: int
characters: int
def register(server: MCPServer, store: DocStore) -> None:
...
@server.tool(annotations=ToolAnnotations(read_only_hint=True))
def count_words(
text: Annotated[str, Field(min_length=1, max_length=10_000)],
) -> WordCount:
"""Count the words and characters in a piece of text."""
return WordCount(words=len(text.split()), characters=len(text))
A few habits that'll save you pain later:
- Write the docstring for the model, not for you. It's how the model decides when to call your tool, so say what it does and what it returns.
- Raise
ToolErrorfor failures you expect, like "that customer doesn't exist." The message goes straight back to the model, so make it something it can act on. Any other exception gets hidden behind a generic error and logged with a traceback, which is what you want for real bugs. - Keep tools small and specific. A few focused tools are easier for the model to pick between than one big tool with a
modeargument. - Add a test in
tests/test_server.py. Theclientfixture hands you a connected client, so most tests are a few lines.
If you outgrow one file, split tools into a package and call each module's register() from build_server() in server.py.
Running tests
uv run pytest # tests, all in-memory
uv run ruff check . # lint
uv run ruff format --check . # formatting
uv run pyright # type check (strict)
uv run python scripts/smoke_stdio.py # launch over real stdio and list tools
CI runs all of these on every push to main and every pull request, on Python 3.11 through 3.14.
Not using uv? A plain virtualenv works too:
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
Running in Docker
The image runs the HTTP transport on port 8000 as a non-root user.
docker build -t mcp-starter .
docker run --rm -p 8000:8000 mcp-starter
One heads-up before you put it on the internet: this template doesn't include auth. Inside the container it binds to 0.0.0.0, and the SDK only turns on DNS rebinding protection by default when it's bound to localhost. Put it behind something that handles auth, or wire up the SDK's auth support, before you expose it.
Project layout
.
├── src/mcp_starter/
│ ├── cli.py # entry point: parses flags, sets up logging, picks a transport
│ ├── server.py # build_server(): creates the MCPServer and registers everything
│ ├── config.py # Settings, loaded from MCP_STARTER_* env vars
│ ├── logging_setup.py # JSON logs to stderr
│ ├── store.py # tiny read-only data layer over the bundled JSON
│ ├── tools.py # search_docs, draft_support_ticket
│ ├── resources.py # docs://{slug}
│ ├── prompts.py # explain_doc
│ └── data/docs.json # sample data
├── tests/ # pytest, using the SDK's in-memory client
├── scripts/smoke_stdio.py
├── Dockerfile
├── .github/workflows/ci.yml
├── pyproject.toml # deps plus ruff, pyright, and pytest config
└── uv.lock
Contributing
Issues and pull requests are welcome. Please run the checks in Running tests before opening a PR. If you're planning something big, open an issue first so we can talk it through.
License
MIT. See LICENSE.
Built by Bonnie Doone Consulting. Need a custom MCP server for your team? Let's talk.
python-starter MCP questions
What transports does this server support?
It supports stdio for local clients like Claude Desktop and streamable HTTP for running as a service.
How do I add my own tools to the server?
You can add tools in the register() function within tools.py, using type hints for input schemas and docstrings for model descriptions.
Does this template include authentication?
No, the template does not include authentication by default; you should put it behind an auth provider before exposing it to the internet.