Skip to main content
Glama
hello-mcp-server

hello-mcp-server

by kuldeepcodes

hello-mcp-python

ci Python 3.14 licence: MIT

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

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:

Licence

MIT — see LICENSE.

Available Tools

4 tools
addAdd 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

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A minimal demonstration server showcasing MCP protocol capabilities including tools, resources, and prompts with basic examples like hello world functionality.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A simple MCP server demonstrating resources, tools, and prompts, including a greeting resource, an addition tool, and a calculation prompt.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A minimal MCP server example demonstrating Tools, Resources, and Prompts. It enables calculations, time queries, note management, and code review prompts via stdio transport.
      3
      MIT