This MCP server tutorial provides a Python-based MCP server implementation with a small, well-documented toolset you can discover, call, and debug through the MCP protocol. The server exposes a collection of example tools designed to validate parameter handling, tool discovery, and response formatting, while also offering debugging hooks and VS Code integration to step through tool discovery, execution, and individual handlers. You can register this server with Claude Desktop to practice end-to-end MCP workflows and use the included test suite to verify basic behavior and error handling. Tools available include hello_world for simple greetings, echo for input/output testing, get_time to fetch time in various formats, math_add for numeric validation, and debug_info to introspect server state and capabilities. These tools are accompanied by a debugging workflow that highlights where discovery and execution flow occur, aiding hands-on learning of the MCP protocol.

Prerequisites:

• Python 3.10 or newer
• pip (comes with Python)
• Basic familiarity with command-line tools

Installation steps:

1. Create and activate a virtual environment

   • On Windows: python -m venv venv venv\Scripts\activate.bat
   • On macOS/Linux: python3 -m venv venv source venv/bin/activate

2. Install the MCP library and project dependencies pip install mcp

   If you have a requirements.txt as shown in the project, you can also run:

   pip install -r requirements.txt

3. Run the server (from the project root or where simple_mcp_server is located) python -m simple_mcp_server

4. Optional: Windows setup script (if you are following the tutorial’s provided scripts) scripts\setup.bat

Notes:

• The tutorial assumes you are using the included simple_mcp_server package structure. Adjust the module path if your setup differs.
• If you clone the repository, ensure your PYTHONPATH includes the project root or install the package in editable mode (pip install -e .) depending on your development workflow.

Tips and common issues:

• When debugging in VS Code, use the pre-configured launch configurations to attach to the MCP server process and set breakpoints at tool discovery (get_all_tools), tool listing (handle_list_tools), tool execution (handle_call_tool), and individual tool handlers.
• If you encounter Unicode or display issues on Windows with the test suite, use the provided test_safe runner (scripts\test_safe.bat) which redirects output to a log file test_output.log.
• Claude Desktop integration requires you to export or copy the Claude configuration from config/claude_desktop.json and update Claude Desktop to recognize the server as simple-mcp-debug. Restart Claude Desktop after changes.
• Review logs/ for debugging information and stack traces, especially if a tool fails or if the server won’t start due to environment or dependency issues.
• The available tools (hello_world, echo, get_time, math_add, debug_info) provide a range of parameter validation scenarios and are useful for exercising the MCP protocol’s discovery and execution paths.