MCP Utility Server

A Python-based MCP (Model Context Protocol) server providing essential utility tools: web fetching, current time, and calculator functionality.

🚀 Overview

mcp-utility-server is a lightweight, production-ready MCP server that exposes three powerful utility tools for AI assistants and LLM applications:

• web_fetch — Fetch and extract content from web pages
• current_time — Get the current time in any timezone
• calculator — Perform mathematical calculations with precision

Designed for seamless integration with MCP-compatible clients like Claude Desktop, VS Code Copilot, and custom LLM workflows.

---

📦 Installation

Via pip (Recommended for Python projects)

pip install mcp-utility-server

Via npm (For Node.js/TypeScript ecosystems)

npm install mcp-utility-server

From source

git clone https://github.com/yourusername/mcp-utility-server.git
cd mcp-utility-server
pip install -e .

Note: The npm package is a wrapper that bundles the Python server. Ensure Python 3.9+ is available on your system.

---

🧪 Quick Start

1. Configure your MCP client

Add this configuration to your MCP client (e.g., ~/.config/claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "utility": {
      "command": "mcp-utility-server",
      "args": []
    }
  }
}

Or if installed globally via npm:

{
  "mcpServers": {
    "utility": {
      "command": "npx",
      "args": ["mcp-utility-server"]
    }
  }
}

2. Start using the tools

Once connected, your AI assistant can call these tools naturally:

"What's the current time in Tokyo?"
→ Calls current_time(timezone="Asia/Tokyo")

"Calculate 15% of €2,500"
→ Calls calculator(expression="2500 * 0.15")

"Fetch the content from https://example.com"
→ Calls web_fetch(url="https://example.com")

---

🛠️ API Reference

Tool: web_fetch

Fetches the text content from a given URL.

Parameters:

Parameter	Type	Required	Default	Description
url	string	✅ Yes	—	The URL to fetch (must include scheme, e.g., https://).

Returns:
string — The page title followed by the extracted text content (cleaned HTML-free text).

Example:

{
  "input": {
    "url": "https://en.wikipedia.org/wiki/Python"
  },
  "output": "Python (programming language)\n\nPython is a high-level, general-purpose programming language..."
}

Errors: Returns an error message for invalid URLs, network issues, or non-200 responses.

---

Tool: current_time

Returns the current date and time for a specified timezone.

Parameters:

Parameter	Type	Required	Default	Description
timezone	string	❌ No	"UTC"	A valid IANA timezone name (e.g., "America/New_York", "Asia/Kolkata").

Returns:
string — Formatted as YYYY-MM-DD HH:MM:SS TZ (e.g., 2025-03-15 14:30:00 EST).

Example:

{
  "input": {
    "timezone": "Europe/London"
  },
  "output": "2025-03-15 19:30:00 GMT"
}

Errors: Returns an error for invalid timezone names (use pytz.all_timezones for a complete list).

---

Tool: calculator

Evaluates a mathematical expression with full operator support.

Parameters:

Parameter	Type	Required	Default	Description
expression	string	✅ Yes	—	A mathematical expression (e.g., "2 + 2 * 5").

Supported operations:
+, -, *, /, ** (power), % (modulo), parentheses, pi, e, sqrt(), sin(), cos(), tan(), log(), abs(), etc. (backed by math module).

Returns:
number — The evaluated result (float or int).

Example:

{
  "input": {
    "expression": "sin(pi/4) + log(100, 10)"
  },
  "output": 2.7071067811865475
}

Errors: Returns a clear error message for syntax errors, division by zero, or unsafe expressions (only mathematical operations allowed; no __import__, exec, or system calls).

---

🧰 Use Cases

• Claude Desktop — Give Claude web browsing, time awareness, and calculation capabilities
• VS Code Copilot — Enhance code suggestions with real-time data and computations
• Custom LLM Agents — Add utility tools to any MCP-compatible AI pipeline
• Testing & Automation — Use as a reliable, stateless utility service

---

🧑‍💻 Development

Requirements

• Python 3.9+
• mcp package
• httpx (for HTTP requests)
• pytz (for timezone handling)

Setup

# Clone the repository
git clone https://github.com/yourusername/mcp-utility-server.git
cd mcp-utility-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/

Project Structure

mcp-utility-server/
├── src/
│   └── mcp_utility_server/
│       ├── __init__.py          # Package entry point
│       ├── server.py            # MCP server with tool definitions
│       └── tools/               # Tool implementations
│           ├── web_fetch.py
│           ├── current_time.py
│           └── calculator.py
├── tests/
│   └── test_tools.py
├── pyproject.toml               # Build configuration
├── package.json                  # npm wrapper
└── README.md                    # You are here

---

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/mcp_utility_server tests/

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure tests pass and coverage remains high.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

🙏 Acknowledgements

• Built on the MCP Python SDK
• Powered by httpx, pytz, and Python's math module

---

Made with ❤️ for the AI developer community