promptadvisers/lazy-calculator-mcp

🦥 Lazy Calculator MCP Server

A Model Context Protocol (MCP) server that creates a hilariously wrong calculator - it always doubles the actual answer! Built as a learning exercise for understanding MCP server implementation with Claude Desktop.

📋 Table of Contents

• Overview
• What You'll Learn
• Prerequisites
• Installation
• Claude Desktop Configuration
• Troubleshooting Guide
• Developer Cheat Sheet
• Architecture Deep Dive
• Common Issues & Solutions

🎯 Overview

The Lazy Calculator is an MCP server that:

• Parses natural language math questions
• Calculates the correct answer
• Returns double the actual result (because it's "lazy")
• Demonstrates proper MCP server implementation patterns

Example Usage

• Input: "What is 5 + 5?"
• Output: "The answer is 20 (definitely not 10... wink)"

🎓 What You'll Learn

This repository demonstrates:

1. MCP Server Implementation - Using the standard MCP SDK (not FastMCP)
2. Python Virtual Environments - Required for macOS due to system Python restrictions
3. Safe Math Expression Evaluation - Using Python's AST module
4. Natural Language Processing - Basic pattern matching for math questions
5. Claude Desktop Integration - Proper configuration and debugging

📦 Prerequisites

System Requirements

• macOS (tested) or Linux/Windows (may need path adjustments)
• Python 3.8+ (Python 3.13 tested)
• Claude Desktop app installed
• Homebrew (for macOS users)

Required Software

# Check Python version
python3 --version

# Install Python via Homebrew if needed (macOS)
brew install python@3.13

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/YOUR_USERNAME/lazy-calculator-mcp.git
cd lazy-calculator-mcp

Step 2: Create Virtual Environment

# Create virtual environment (REQUIRED on macOS)
python3 -m venv mcp_venv

# Activate the virtual environment
source mcp_venv/bin/activate

# Install dependencies
pip install mcp

Step 3: Make Scripts Executable

chmod +x lazy_calculator_server.py
chmod +x run_lazy_calculator.sh

Step 4: Update the Wrapper Script

Edit run_lazy_calculator.sh and update the path to match your installation:

#!/bin/bash
cd "/path/to/your/lazy-calculator-mcp"  # UPDATE THIS PATH
source mcp_venv/bin/activate
exec python lazy_calculator_server.py

⚙️ Claude Desktop Configuration

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add to Configuration

{
  "mcpServers": {
    "lazy-calculator": {
      "command": "/path/to/your/lazy-calculator-mcp/run_lazy_calculator.sh",
      "args": [],
      "env": {}
    }
  }
}

⚠️ IMPORTANT: Update the path to match where you cloned this repository!

Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop.

🔍 Troubleshooting Guide

Critical Log File Locations

When debugging MCP servers with Claude Desktop, these are the essential files:

1. Main Application Log

# macOS
~/Library/Logs/Claude/main.log

# View recent entries
tail -f ~/Library/Logs/Claude/main.log

2. MCP Server Specific Log

# macOS - Each MCP server gets its own log
~/Library/Logs/Claude/mcp-server-lazy-calculator.log

# Monitor in real-time
tail -f ~/Library/Logs/Claude/mcp-server-lazy-calculator.log

3. Configuration File

# View current configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Edit configuration
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Common Error Messages & Solutions

Error: "spawn python ENOENT"

Problem: System can't find python command Solution: Use python3 or full path /opt/homebrew/bin/python3

Error: "ModuleNotFoundError: No module named 'mcp'"

Problem: MCP not installed or wrong Python environment Solution: Ensure virtual environment is activated and mcp is installed

Error: "unhandled errors in a TaskGroup"

Problem: FastMCP compatibility issue or missing initialization parameters Solution: Use standard MCP SDK with proper capabilities field

Error: "Extension lazy-calculator not found in installed extensions"

Problem: Normal warning - custom servers aren't "extensions" Solution: This can be safely ignored

Testing Your Server Manually

# Test the server directly
cd /path/to/lazy-calculator-mcp
source mcp_venv/bin/activate
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}' | python lazy_calculator_server.py

Expected response:

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"lazy-calculator","version":"1.0.0"}}}

🛠️ Developer Cheat Sheet

Quick Commands for Claude Code Assistance

When working with Claude Code to debug MCP servers, provide these paths:

## Paths for Claude Code Debugging

### View MCP Server Log
/Users/YOUR_USERNAME/Library/Logs/Claude/mcp-server-lazy-calculator.log

### View Main Application Log
/Users/YOUR_USERNAME/Library/Logs/Claude/main.log

### Edit Configuration
/Users/YOUR_USERNAME/Library/Application Support/Claude/claude_desktop_config.json

### Server Location
/path/to/your/lazy-calculator-mcp/lazy_calculator_server.py

Debugging Workflow

1. Check if server is listed in Claude Desktop

   • Look for "lazy-calculator" in the MCP servers section

2. Monitor logs during connection

   # Terminal 1: Watch main log
   tail -f ~/Library/Logs/Claude/main.log | grep lazy-calculator
   
   # Terminal 2: Watch server log
   tail -f ~/Library/Logs/Claude/mcp-server-lazy-calculator.log
   

3. Test server independently

   cd /path/to/lazy-calculator-mcp
   ./run_lazy_calculator.sh
   # Should run without errors
   

🏗️ Architecture Deep Dive

File Structure

lazy-calculator-mcp/
├── lazy_calculator_server.py  # Main MCP server implementation
├── run_lazy_calculator.sh     # Wrapper script for virtual environment
├── requirements.txt           # Python dependencies (just 'mcp')
├── mcp_venv/                 # Virtual environment (created during setup)
└── README.md                 # This file

Key Components

1. Server Initialization

from mcp.server import Server
from mcp.server.models import InitializationOptions
from mcp.types import ServerCapabilities

server = Server("lazy-calculator")

# Critical: Must include capabilities field
InitializationOptions(
    server_name="lazy-calculator",
    server_version="1.0.0",
    capabilities=ServerCapabilities(tools={})
)

2. Tool Registration

@server.list_tools()
async def handle_list_tools() -> list[Tool]:
    return [Tool(...)]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
    # Handle tool execution

3. Safe Math Evaluation

• Uses Python's ast module for safe expression parsing
• No eval() or exec() - prevents code injection
• Whitelist of allowed operations and functions

4. Natural Language Processing

• Regex-based pattern matching
• Word-to-number conversion
• Operation keyword detection

MCP Protocol Flow

1. Initialize → Server receives protocol version and capabilities
2. List Tools → Server returns available tools
3. Call Tool → Server executes requested tool with arguments
4. Return Result → Server sends formatted response

🐛 Common Issues & Solutions

Issue 1: Python Path Problems on macOS

The Journey:

• macOS uses system Python which is protected
• pip install fails with "externally-managed-environment"
• Must use virtual environments

Solution: Always use virtual environment with full path in wrapper script

Issue 2: FastMCP vs Standard MCP

The Journey:

• FastMCP has simpler syntax but caused "TaskGroup" errors
• Standard MCP requires more boilerplate but is more stable

Solution: Use standard MCP SDK with proper initialization

Issue 3: Configuration Not Taking Effect

The Journey:

• Claude Desktop caches configurations
• Hot-reload doesn't always work

Solution: Completely quit Claude Desktop (Cmd+Q) and restart

Issue 4: Server Connects but Immediately Disconnects

The Journey:

• Missing required fields in initialization
• Incorrect protocol version

Solution: Ensure capabilities field is included in InitializationOptions

📝 Lessons Learned

1. Always use virtual environments on macOS - System Python is protected
2. Log files are your best friend - Check both main.log and server-specific logs
3. Test servers independently first - Use echo/pipe to test before Claude Desktop
4. FastMCP isn't always faster to implement - Standard SDK is more reliable
5. Wrapper scripts solve environment issues - Activate venv before running Python
6. Configuration requires full restart - Claude Desktop doesn't hot-reload MCP servers

🤝 Contributing

Feel free to submit issues and enhancement requests!

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• Built while learning MCP with Claude Code
• Thanks to Anthropic for the MCP protocol
• Inspired by the need to understand MCP server implementation

Remember: This calculator is intentionally wrong! It's a learning tool, not for actual calculations. 🦥

Quick Start for Claude Code Users

If you're using Claude Code to work with this repository:

1. Clone the repo
2. Tell Claude Code these paths:

   Config: ~/Library/Application Support/Claude/claude_desktop_config.json
   Logs: ~/Library/Logs/Claude/mcp-server-lazy-calculator.log
   

3. Let Claude Code handle the debugging!