MCP Server Demo (Python)

Quickstart (local run)

Create and activate a virtual environment.

python -m venv .venv
source .venv/bin/activate

Install Python dependencies.

pip install -U pip
pip install -r requirements.txt
pip install -e .

Set up environment variables.

cp .env.example .env

Fill in your OPENAI_API_KEY and keep MCP_DEMO_DB_PATH=demo.db. If you want to use file tools, set MCP_FILE_OPS_ROOT to a local folder path that the server is allowed to manage.

You will fill out the MCP_SERVER_URL in a later step

If you plan to expose your local MCP server publicly, make sure ngrok is installed sudo snap install ngrok and your account is set up and authenticated first. You can set up an account for free. Once set up, add token using terminal ngrok config add-authtoken <AUTHTOKEN> You can find the token on https://dashboard.ngrok.com/get-started/your-authtoken
Start the MCP server (HTTP transport).

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 MCP_PATH=/mcp mcp-server-demo

In a new terminal, start ngrok.

ngrok http 8000

Once you have ngrok running, you need to update MCP_SERVER_URL in your .env file use the address from 'Forwarding'. Your .env will now look like MCP_SERVER_URL=<Full forwarding Address>/mcp

(Optional) In another terminal, run MCP Inspector.

npx @modelcontextprotocol/inspector

It should open up a web browser. In the left hand panel update Command to be mcp-server-demo Press connect. You can select "tools" in the top menu to test the available tools and see history and notifications at the bottom of the page

(Optional) Launch the Streamlit client.

streamlit run web_client.py

A from-scratch local MCP server with tools for weather, SQLite reads, and local file operations:

weather(city) → current weather via wttr.in
query_db(sql) → read-only SQLite SELECT query
make_directory(path) → create directories inside MCP_FILE_OPS_ROOT
move_file(source_path, destination_path) → move files inside MCP_FILE_OPS_ROOT
move_files_by_glob(source_dir, pattern, destination_dir) → move many files in one call (e.g., *.txt)
list_files(path=".") → list files in a folder inside MCP_FILE_OPS_ROOT
list_directories(path=".") → list directories in a folder inside MCP_FILE_OPS_ROOT
read_file(path) → read text files inside MCP_FILE_OPS_ROOT
inspect_file(path, preview_chars=4000, include_base64=False) → metadata + preview for text/csv/image files
analyze_image_with_openai(path, prompt, model='gpt-4.1-mini') → send image to OpenAI vision-capable model

Notes

Default local MCP endpoint is: http://127.0.0.1:8000/mcp
The server creates demo.db automatically with sample rows.
npx requires Node.js/npm installed locally.
streamlit is included in requirements.txt.

OpenAI API integration option

Ensure .env includes your key and MCP server URL.
Start server in HTTP mode.
Run:

python client_openai_api.py

Tool behavior

`weather(city: str)`

Returns JSON summary fields including temperature, feels-like, humidity, wind, and short conditions.

`query_db(sql: str)`

Allows only SELECT ... queries.
Returns rows as JSON.
Rejects non-SELECT SQL for safety in this starter demo.

Project files

server.py — FastMCP server + tool definitions.
client_openai_api.py — simple OpenAI API call that can invoke MCP tools.
web_client.py — Streamlit chat client.
pyproject.toml — package metadata + script entrypoint.
requirements.txt — pinned runtime dependencies for local setup.

File operation tools

All file operations are constrained to MCP_FILE_OPS_ROOT.
The server rejects paths that try to escape that root.
MCP_FILE_OPS_ROOT directories are created automatically if they do not exist.

mcp-server-demo