MCP Utility Server

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

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

server1.py — Daily Utilities Pro

Includes the basic tools above, plus:

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

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

Connect a client to the container

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

Environment variables

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

1. Open Cursor Settings → Tools & MCP → Add MCP Server
2. 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

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

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

1. 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

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

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

Official links

• Model Context Protocol
• Build an MCP Server (tutorial)
• Python SDK
• Awesome MCP Servers

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