hello-mcp-python

A hello-world Model Context Protocol server in Python, plus a console chat client that drives its tools with a small local LLM.

It is deliberately small, but it is not a toy. It uses the official Python MCP SDK, serves both transports (stdio and streamable HTTP), is covered by 29 automated tests including real protocol round-trips over a real pipe, and handles the things that actually break MCP servers in practice.

New to MCP? Start with GETTING-STARTED.md — it builds this entire project from an empty directory, one step at a time, explaining every dependency and every file.

Quick start

Prerequisites: Python 3.14 or newer.

git clone https://github.com/kuldeepcodes/hello-mcp-python.git
cd hello-mcp-python

python -m venv .venv
source .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1

python -m pip install -e ".[dev]"
python -m pytest                 # 29 tests

# Works with no model at all, using deterministic keyword routing
python -m hello_mcp.chat --provider none --ask "hello Kuldeep"

For real conversation, install Ollama and pull a small model:

ollama pull phi3          # ~2.2 GB, works with the prompt planner
python -m hello_mcp.chat --ask "what is 17.5 plus 24.25?"

Server tools

Tool	Description
say_hello	Greets someone by name in 10 languages: en, es, fr, de, it, pt, hi, ja, zh, ar.
echo	Returns a message verbatim; useful for connection checks.
get_server_time	Returns structured utc, local, timeZone, utcOffset and human fields.
add	Adds two numbers with decimal formatting, so 0.1 + 0.2 is 0.3.

The server also exposes prompts (friendly_greeting, summarize_capabilities) and resources (hello://server/info, plus templated hello://greetings/{language}).

Running the server

# stdio, for local MCP clients
.\.venv\Scripts\python.exe -m hello_mcp.server

# streamable HTTP, endpoint /mcp and liveness /healthz
.\.venv\Scripts\python.exe -m hello_mcp.server --http --port 5099

In stdio mode, stdout is reserved for JSON-RPC. All logging is deliberately sent to stderr.

MCP client configuration

VS Code or Claude Desktop-style stdio config. Use absolute paths — the client does not run from your project directory:

{
  "mcpServers": {
    "hello-mcp-python": {
      "command": "/absolute/path/to/hello-mcp-python/.venv/bin/python",
      "args": ["-m", "hello_mcp.server"],
      "cwd": "/absolute/path/to/hello-mcp-python"
    }
  }
}

On Windows the interpreter is ...\\.venv\\Scripts\\python.exe, and backslashes must be escaped in JSON.

HTTP clients can connect to http://127.0.0.1:5099/mcp after starting the server with --http.

Chat strategies

Strategy	When chosen	How it works
Native tool calling	The model accepts a probe request with a tools array.	The model emits tool calls directly.
Prompt planner	The model is reachable but rejects tools, as phi3 does in Ollama.	The app shows tool names, descriptions, and JSON schemas, asks for one JSON decision, executes it, then asks the model to phrase the result.
Offline routing	No model is reachable, or --provider none is used.	Deterministic keyword rules support hello NAME, what time is it, add 2 and 3, and echo ....

The selected strategy and reason are printed at startup.

Real transcript

  hello-mcp-chat v1.0.0
  a Model Context Protocol client for Python

Connected to hello-mcp-server (4 tools)
Model strategy: prompt planner - Ollama says this model does not support tools

  [tool] add {"a": 17.5, "b": 24.25} -> 41.75
bot> The sum of 17.5 and 24.25 is 41.75.

Tests and linting

.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m pytest

The integration tests spawn the real server over stdio, perform a real MCP handshake, list tools, call tools, list prompts, read resources, and assert stdout contains only JSON-RPC.

Limitations

• The prompt planner is intentionally conservative and less reliable than native tool calling.
• HTTP transport has no authentication; this is a local teaching project.
• Windows needs the tzdata package for IANA time zones such as Asia/Kolkata.

Built with

• mcp==2.0.0 — official Python MCP SDK. In this version the ergonomic API is mcp.server.mcpserver.MCPServer; older examples may call this style FastMCP.
• httpx — Ollama and OpenAI-compatible HTTP calls.
• pytest — unit and integration tests.
• ruff — linting and formatting.

The same project in other languages

This is one of three parallel implementations, same tools, same behaviour, same lessons:

• hello-mcp-dotnet — C# / .NET 10
• hello-mcp-java — Java 17 / Spring Boot
• hello-mcp-python — Python 3.14+ (you are here)

Licence

MIT — see LICENSE.