MCP Utility Server

A beginner-friendly Model Context Protocol (MCP) project in Python with two server implementations:

| File | Description | |------|-------------| | server.py | Core MVP — time, math, internet quotes, dad jokes | | server1.py | Pro server — file tools, web search, optional LangChain agent (OpenAI / Groq) |

Includes a test client (mcp-client.py) and support for stdio (local) and SSE (remote) transports.

What is MCP?

Model Context Protocol is an open standard that lets AI applications (Cursor, Claude Desktop, VS Code, custom agents, etc.) connect to external tools and data in a standardized way.

Your MCP server exposes Tools (actions the AI can call). This project focuses on tools.

Tools

`server.py` — Daily Utilities

| Tool | Description | Type | |------|-------------|------| | get_current_datetime | Current date and time, formatted | Sync | | add_numbers | Adds two numbers | Sync | | multiply_numbers | Multiplies two numbers | Sync | | safe_calculate | Safely evaluates math expressions (no eval) | Sync | | get_motivational_quote | Fetches a quote from the internet (with fallbacks) | Async | | get_dad_joke | Fetches a dad joke from icanhazdadjoke.com | Async |

`server1.py` — Daily Utilities Pro

Includes the basic tools above, plus:

| Tool | Description | |------|-------------| | list_directory | Lists files in allowed directories (project, Documents, Downloads) | | read_file | Reads a text file (size-limited, sandboxed) | | web_search | DuckDuckGo web search (requires langchain extra) | | enhance_prompt | Simple prompt improvement helper | | ask_smart | LangChain agent with session memory (requires API key + langchain extra) |

Quick Start

Prerequisites

Python 3.10+
uv (recommended)

Install

git clone https://github.com/gyannetics/mcp-utility-server.git
cd mcp-utility-server

# Core dependencies only (server.py)
uv sync

# All features (server1.py, SSE, LangChain)
uv sync --all-extras

Optional dependency groups

| Extra | Packages | Used by | |-------|----------|---------| | (core) | mcp, httpx, python-dotenv | Both servers | | sse | fastapi, uvicorn | Remote SSE mode | | langchain | LangChain, OpenAI/Groq, DuckDuckGo search | server1.py agent & web search | | all | Everything above | Full Pro setup |

uv sync --extra sse
uv sync --extra langchain

Environment variables (`server1.py`)

Copy .env and add your keys (at least one for the smart agent):

OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk-...

Groq is preferred when both keys are set. Basic tools work without any API key.

Run the Server

Stdio (local — Claude Desktop, Cursor)

uv run server.py
# or
uv run server1.py

The server waits for MCP connections over stdin/stdout.

SSE (remote / Docker)

uv run server1.py sse
# MCP endpoint:  http://localhost:8000/sse
# Health check:  http://localhost:8000/health

Requires the sse extra (uv sync --extra sse or --all-extras).

Docker

The container runs server1.py in SSE mode (the Pro server) with a built-in health check.

Quick start

# Build and run with Docker Compose (loads .env if present)
docker compose up --build

# Or plain Docker
docker build -t mcp-utility-server .
docker run --rm -p 8000:8000 --env-file .env mcp-utility-server

Endpoints

| URL | Purpose | |-----|---------| | http://localhost:8000/health | Liveness probe (JSON {"status": "healthy", ...}) | | http://localhost:8000/sse | MCP SSE transport for remote clients |

Connect a client to the container

uv run mcp-client.py --sse http://localhost:8000/sse

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | HOST | 0.0.0.0 | Bind address inside the container | | PORT | 8000 | HTTP port | | OPENAI_API_KEY | — | Enables the ask_smart LangChain tool | | GROQ_API_KEY | — | Enables ask_smart via Groq (preferred if both set) |

Run the core server instead

To containerize server.py instead of server1.py, change the CMD in the Dockerfile:

CMD ["python", "server.py", "sse"]

Test with the MCP Client

# Full demo via stdio (spawns server.py automatically)
uv run mcp-client.py

# Test a single tool
uv run mcp-client.py --tool get_motivational_quote

# Connect to a running SSE server (local or Docker)
uv run server1.py sse
uv run mcp-client.py --sse http://localhost:8000/sse

Use with Cursor

Open Cursor Settings → Tools & MCP → Add MCP Server
Or edit %USERPROFILE%\.cursor\mcp.json (Windows) / ~/.cursor/mcp.json (macOS/Linux):

{
  "mcpServers": {
    "daily-utilities": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\mcp-utility-server",
        "run",
        "server.py"
      ]
    }
  }
}

Use the full absolute path to this project. Reload Cursor after saving.

Example prompts:

"What time is it?"
"Calculate 15 * 7 + 22"
"Tell me a dad joke"
"Give me a motivational quote"

Use with Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config
Add to claude_desktop_config.json:

{
  "mcpServers": {
    "daily-utilities": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-utility-server",
        "run",
        "server.py"
      ]
    }
  }
}

Fully quit and restart Claude Desktop.

Project Structure

mcp-utility-server/
├── server.py           # Core MCP server
├── server1.py          # Pro server (default for Docker)
├── mcp-client.py       # Test client (stdio + SSE)
├── Dockerfile          # Container image (server1.py SSE mode)
├── docker-compose.yml  # Local container orchestration
├── pyproject.toml      # Dependencies and optional extras
├── .env                # API keys (not committed)
├── .dockerignore
├── .gitignore
└── README.md

Troubleshooting

| Issue | Fix | |-------|-----| | Server not appearing in Cursor/Claude | Check absolute path in config; reload or restart the app | | ImportError for fastapi / langchain | Run uv sync --all-extras | | Client import error in mcp-client.py | Use the project venv: uv run mcp-client.py | | Quotes/jokes time out | Network tools use a 30s timeout; check internet access | | stdout errors in stdio mode | Never use print() — log to stderr with logging | | pip conflicts in Anaconda | Use this project's .venv via uv sync, not global pip |

Cursor MCP logs: View → Output → select MCP from the dropdown.

Claude Desktop logs (macOS): ~/Library/Logs/Claude/mcp*.log

Learning & Resources

This project demonstrates:

Building MCP servers with FastMCP
Auto-generated tool schemas from type hints and docstrings
Sync vs async tools
Safe HTTP calls with fallbacks
Optional LangChain agent integration
Stdio and SSE transports
A Python MCP client using ClientSession

Extend it

Add Resources — expose files or data as readable context
Add Prompts — reusable prompt templates
Persist data — todo lists, notes, session history to disk
Deploy remotely — SSE on Railway, Fly.io, or similar
Connect more APIs — Notion, GitHub, databases, etc.

Official links

---

Built as an educational MCP starter. Experiment, extend, and have fun.

MCP Utility Server