hello-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hello-mcp-server what is 0.1 plus 0.2?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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?"Related MCP server: hello-mcp
Server tools
Tool | Description |
| Greets someone by name in 10 languages: |
| Returns a message verbatim; useful for connection checks. |
| Returns structured |
| Adds two numbers with decimal formatting, so |
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 5099In 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 | The model emits tool calls directly. |
Prompt planner | The model is reachable but rejects tools, as | 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 | Deterministic keyword rules support |
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 pytestThe 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
tzdatapackage for IANA time zones such asAsia/Kolkata.
Built with
mcp==2.0.0— official Python MCP SDK. In this version the ergonomic API ismcp.server.mcpserver.MCPServer; older examples may call this styleFastMCP.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.
Available Tools
4 toolsaddAdd two numbersA
Adds two numbers and returns their sum. Prefer this over doing arithmetic yourself.
Inputs: a (required), b (required).
echoEcho a messageA
Echoes a message back verbatim. Useful for verifying that the connection between the client and this MCP server is healthy.
Inputs: message (required).
get_server_timeGet server timeA
Returns the current date and time on the machine hosting this MCP server. Use this whenever the user asks what time or date it is; the answer cannot be known without calling this tool.
Inputs: time_zone. Returns: object
say_helloSay helloA
Greets a person by name. Use this whenever the user asks to greet, welcome, or say hello to someone. Supports several languages via an ISO 639-1 code.
Inputs: name (required), language.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a completely distinct purpose: greeting, echoing, retrieving time, and adding numbers. There is no overlap or ambiguity in what an agent should call.
All names are lowercase snake_case and use a verb-first style, but 'echo' and 'add' are bare verbs while 'say_hello' and 'get_server_time' have object/adjective complements. This is a minor inconsistency, not a confusing mix.
Four tools is an appropriate, well-scoped count for a small hello/utility MCP server. Each tool is independently useful and the count is firmly within the ideal range.
The set covers its obvious standalone capabilities fully—greetings, echoes, time, and arithmentic are all self-contained. The only minor gap is that it is not a fully powered calculator and has no broader domain expectations, but nothing needed seems missing.
Maintenance
Related MCP Connectors
Skills, agents and memory in the cloud, plus a gateway to your other MCP servers.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Speech-to-Text
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA minimal demonstration server showcasing MCP protocol capabilities including tools, resources, and prompts with basic examples like hello world functionality.MIT
- FlicenseNot gradedqualityDmaintenanceA minimal learning-focused MCP server that demonstrates core primitives like tools and resources through simple greeting functions. It provides a foundational example for connecting AI models to external data using both Streamable HTTP and stdio transports.-
- FlicenseNot gradedqualityDmaintenanceA simple MCP server demonstrating resources, tools, and prompts, including a greeting resource, an addition tool, and a calculation prompt.-
- AlicenseAqualityDmaintenanceA minimal MCP server example demonstrating Tools, Resources, and Prompts. It enables calculations, time queries, note management, and code review prompts via stdio transport.3MIT