Hello MCP Server
A simple MCP (Model Context Protocol) server that provides a greeting tool,
built with the MCP Python SDK v2 (MCPServer).
* It is not necessary to listen on a port. The default transport is stdio.
* It talks to the client over standard input and output, so whatever (e.g., Ollama, Claude Code) launches it as a subprocess (like our MCP client) communicates with it directly
Terminology
In MCP, "server" names the program's role, not whether it uses the network. This
project is a stdio MCP server (also called a local MCP server). The MCP spec defines
three roles:
| Role | What it is | In this project |
|---|---|---|
| Host | The app the user works in, which runs the model | Claude Desktop, Claude Code, or Continue.dev / Open WebUI with Ollama |
| Client | The connection the host opens to one server | Built into each host, or client/test_client.py |
| Server | The program that provides tools, resources and prompts | server.py (stdio) or http_server.py (HTTP) |
The transport (stdio or streamable-http) only decides how messages travel. With
stdio, the client starts the server as a subprocess, so no port is needed.
Prerequisites
- Python 3.10 or higher (
mcpwon't install on older versions; on macOS the
systempython3may be 3.9, so use a newer one, e.g. from Homebrew oruv)
Installation
- Create and activate a virtual environment:```bash
python3 -m venv venv # make sure this python3 is 3.10+
source venv/bin/activate # On Windows: venv\Scripts\activate
2. Install dependencies:```bash
pip install -r requirements.txt
Or using pyproject.toml:```bash
pip install -e .
## Running the Server
Run the server directly:```bash
python server.py
The server communicates over stdio and is designed to be launched by an MCP client,
so running it by hand just waits for input (press Ctrl+C to exit). To try it out
interactively, use the MCP Inspector (see Testing with MCP Inspector).
> Note: MCP clients usually launch the server with an absolute command path and
> without activating your virtualenv. In the client configs below, point command at
> the virtualenv's interpreter (e.g. /absolute/path/to/hello-py-mcp/venv/bin/python,
> or venv\Scripts\python.exe on Windows), not a bare python. Otherwise the
> client may pick a Python that doesn't have mcp installed.
Running the HTTP Server
http_server.py provides the same hello tool over the
Streamable HTTP transport instead of stdio. It listens on 0.0.0.0:1234, so other
machines on your network can reach it too.
Start it and leave it running (with HTTP, clients connect to a running server instead
of launching it):```bash
venv/bin/python http_server.py
The MCP endpoint is `http://127.0.0.1:1234/mcp` (from another machine, use this
computer's IP address instead of `127.0.0.1`).
> **Warning:** The server has no authentication. Anyone who can reach port 1234 can
> call its tools.
### Using it from a browser
Opening `http://127.0.0.1:1234/mcp` directly in a browser **won't work**. The endpoint
speaks MCP (JSON-RPC with a handshake), not plain web pages, so the browser just gets
an error:```json
{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Bad Request: Missing session ID"}}
An MCP client first sends POST /mcp with an initialize message. The server replies
with a session ID in the Mcp-Session-Id header, and the client includes that header
in every later request. A browser's plain GET /mcp skips the handshake and has no
session ID, so the server rejects it.
Use the MCP Inspector, a web UI that acts as an MCP client (requires Node.js):
-
With
http_server.pyrunning, start the Inspector in another terminal:bash npx @modelcontextprotocol/inspector -
It opens a page in your browser (usually
http://localhost:6274). If it doesn't,
open the URL printed in the terminal, including itsMCP_PROXY_AUTH_TOKENpart. - In the left panel, set:
- Transport Type:Streamable HTTP
- URL:http://127.0.0.1:1234/mcp - Click Connect.
- Open the Tools tab, click List Tools, then select
hello. - Enter a
name(e.g.Alice) and click Run Tool. The result isHello, Alice!.
Using the plain HTML client
http_client/index.html is an MCP client written in plain
HTML and JavaScript, with no libraries or build step. With http_server.py running,
open the file in your browser (double-click it, or open http_client/index.html on
macOS), then click Connect, List Tools and Run Tool.
The Protocol log on the page shows every HTTP request and response, so you can see
each step the Inspector normally hides:
initialize(POST): the handshake. The server replies with its info and an
Mcp-Session-Idheader.notifications/initialized(POST): confirms the handshake (HTTP202, no body).tools/listandtools/call(POST): sent with theMcp-Session-Idand
MCP-Protocol-Versionheaders.- Disconnect sends
DELETEto end the session.
This works because http_server.py enables CORS. A page opened from disk has the
origin null, which differs from http://127.0.0.1:1234, so the browser blocks its
requests unless the server allows them. The server also exposes the Mcp-Session-Id
header, which JavaScript can't read otherwise.
> Note: CORS allows every origin (*), so any web page open in your browser could
> call this server too. That's fine for this demo, but restrict allow_origins for
> anything real.
Using it with Claude Code
Register it by URL instead of by command:```bash
claude mcp add --transport http hello-http http://127.0.0.1:1234/mcp
## Available Tools
### `hello`
Says hello to someone.
**Parameters:**
- `name` (string, required): The name of the person to greet
**Example response:** `Hello, Alice!`
## Using with Claude Desktop
Add this to your Claude Desktop configuration file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"hello": {
"command": "/absolute/path/to/hello-py-mcp/venv/bin/python",
"args": ["/absolute/path/to/hello-py-mcp/server.py"]
}
}
}
Replace /absolute/path/to/hello-py-mcp with the actual path to this project, then restart Claude Desktop.
Using with Claude Code
Register the server with Claude Code:```bash
% claude mcp add hello -- /absolute/path/to/hello-py-mcp/venv/bin/python /absolute/path/to/hello-py-mcp/server.py
* The packages in venv will be included by above command
Then run `claude mcp list` to check that it's connected, or type `/mcp` inside a Claude Code session.```bash
% claude mcp list
claude.ai Claude Docs: https://api.anthropic.com/v1/pages/mcp - ✔ Connected
claude.ai Gmail: https://gmailmcp.googleapis.com/mcp/v1 - ✔ Connected
claude.ai Google Drive: https://drivemcp.googleapis.com/mcp/v1 - ✔ Connected
claude.ai Google Calendar: https://calendarmcp.googleapis.com/mcp/v1 - ✔ Connected
hello: /Users/ywlee/Desktop/code/projects/hello-py-mcp/venv/bin/python3
/Users/ywlee/Desktop/code/projects/hello-py-mcp/server.py - ✔ Connected
Use the prompt Use the hello tool to greet Alice in claude code```
Claude Code v2.1.323
Opus 5.5 · Claude Pro
~/Desktop/code/projects/hello-py-mcp
❯ Use the hello tool to greet Alice
Called hello
I called the hello tool with the name Alice, and it returned: "Hello, Alice!"
✻ Sautéed for 4s · done 3:13 PM
## Using with Ollama
Ollama doesn't natively support MCP servers, but you can use them together through various methods:
### Option 1: Using Continue.dev (VS Code/JetBrains)
Continue.dev is an IDE extension that supports both Ollama and MCP servers.
1. Install the Continue extension in VS Code or JetBrains
2. Configure your `~/.continue/config.json`:```json
{
"models": [{
"title": "Ollama",
"provider": "ollama",
"model": "llama3.2"
}],
"mcpServers": {
"hello": {
"command": "/absolute/path/to/hello-py-mcp/venv/bin/python",
"args": ["/absolute/path/to/hello-py-mcp/server.py"]
}
}
}
Replace /absolute/path/to/hello-py-mcp with the actual path to this project and adjust the Ollama model name as needed.
Option 2: Using Open WebUI
Open WebUI supports MCP servers and works with Ollama.
- Install and run Open WebUI (connects to Ollama by default)
- Configure MCP server in Settings → Tools → MCP Servers
Option 3: Custom Integration
You can build a custom client using the MCP Python SDK and Ollama's API:```python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import ollama
async def main():
# Connect to MCP server
server_params = StdioServerParameters(
command="python",
args=["server.py"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# List available tools
tools = await session.list_tools()
print(f"Available tools: {tools}")
# Use Ollama to generate a response
response = ollama.chat(
model='llama3.2',
messages=[{
'role': 'user',
'content': 'Say hello to Alice'
}]
)
# Call MCP tool based on LLM response
result = await session.call_tool("hello", {"name": "Alice"})
print(result)
if name == "main":
asyncio.run(main())
## Automated Test Client
`client/test_client.py` starts the server over stdio and runs
end-to-end protocol checks (handshake, ping, tools/list, valid and invalid tool calls).
It exits with a non-zero status if any check fails:```bash
python client/test_client.py
To test http_server.py instead, start it and pass its URL:```bash
python client/test_client.py http://127.0.0.1:1234/mcp
See `client/README.md` for details.
## Testing with MCP Inspector
You can test the MCP server directly using the MCP Inspector (requires Node.js).
Run this from the project directory with the virtualenv activated:```bash
npx @modelcontextprotocol/inspector python server.py
This opens a web interface where you can test your MCP server's tools manually, regardless of which LLM you plan to use.