MCP Calculator Server

This repository provides a minimal Model Context Protocol (MCP) server that exposes simple calculator tools (add, subtract, multiply, divide). It's intended as a clean example you can publish to GitHub and use as a starting point for MCP work.

This README covers: setup, running, testing, and publishing the project.

Quick start (Windows PowerShell)

1. Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install the MCP SDK (inside the venv):

pip install "mcp[cli]"

3. Run the server (stdio transport):

python calculator_server.py

4. Run tests (if you use pytest):

python -m pytest

Requirements

• Python 3.11+ (3.10 may work but 3.11+ recommended)
• mcp package (install with pip install "mcp[cli]")

Running the server

Via stdio (standard input/output)

Default transport — recommended for local testing and Claude Desktop integration:

python calculator_server.py

This starts the server using stdio, which communicates via standard input/output streams. The server will wait for connections from MCP clients (e.g., Claude Desktop, MCP Inspector).

Via HTTP (streamable-http transport)

For local testing over HTTP:

python calculator_server.py --transport streamable-http --host 127.0.0.1 --port 8000

This binds the server to http://127.0.0.1:8000 (localhost only). You can then connect MCP clients via HTTP to this address.

For external access (binding to all interfaces):

python calculator_server.py --transport streamable-http --host 0.0.0.0 --port 8080

⚠️ Warning: Binding to 0.0.0.0 or an explicit external IP will disable DNS rebinding protection, allowing external clients to connect. This may expose the server to DNS rebinding attacks. Only use external binding when you understand the security implications and trust the clients connecting to it.

Custom host/port examples:

# Bind to a specific IP address
python calculator_server.py --transport streamable-http --host 192.168.1.100 --port 5000

# Bind to localhost with a different port
python calculator_server.py --transport streamable-http --host 127.0.0.1 --port 9000

Claude Desktop Configuration

To use the calculator server with Claude Desktop, add the following configuration to your claude_desktop_config.json file (typically located at ~/.claude/claude_desktop_config.json on macOS/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows).

Via stdio (recommended for Claude Desktop)

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\mcp2\\VSMCP\\VSMCP",
        "run",
        "python",
        "calculator_server.py"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}

Replace F:\\mcp2\\VSMCP\\VSMCP with the full path to your project directory.

After updating the config, restart Claude Desktop. The calculator tools will be available in your conversations.

Via HTTP streamable (localhost)

If you prefer to run the server over HTTP on localhost:

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\mcp2\\VSMCP\\VSMCP",
        "run",
        "python",
        "calculator_server.py",
        "--transport",
        "streamable-http",
        "--host",
        "127.0.0.1",
        "--port",
        "8000"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}

Replace F:\\mcp2\\VSMCP\\VSMCP with the full path to your project directory.

After updating the config, restart Claude Desktop.

Via HTTP streamable (external access)

If you want external clients to access the server over HTTP:

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\mcp2\\VSMCP\\VSMCP",
        "run",
        "python",
        "calculator_server.py",
        "--transport",
        "streamable-http",
        "--host",
        "0.0.0.0",
        "--port",
        "8080"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}

⚠️ Warning: Binding to 0.0.0.0 disables DNS rebinding protection. Only do this if you understand the security implications.

Tests

• Run the included tests with:

python -m pytest

or, if you prefer the single-file runner:

python test_mcp.py

Files removed from repo

I removed the following build / artifact files from the repository because they are not needed in source control:

• __pycache__/ (Python bytecode caches)
• mcp_calculator_server.egg-info/ (packaging metadata)
• nodejs.zip (archival artifact)

If you want any of these preserved, let me know and I can restore them.

Git / Publishing suggestions

• Add these entries to .gitignore (this repo already contains a .gitignore):

.venv/
__pycache__/
*.py[cod]
*.egg-info/
node_modules/

• To publish to GitHub:

git init
git add .
git commit -m "Initial commit: MCP calculator server"
git branch -M main
git remote add origin https://github.com/<your-user>/<your-repo>.git
git push -u origin main

Next steps

• Add a requirements.txt or pyproject.toml dependency specification if you want reproducible installs.
• Add CI (GitHub Actions) to run tests on push.

If you want, I can:

• run the test suite locally and update this README with exact commands I used,
• add a requirements.txt or pyproject.toml snippet,
• create a simple GitHub Actions workflow to run tests on push.

---

calculator_server.py is the main entrypoint; see its docstring and code for details.

This launches a web-based UI where you can test your calculator tools.

6. In the inspector, connect to stdio and select your running server

7. Try calling a tool, for example:

   • Tool: add
   • Parameters: {"a": 5, "b": 3}
   • Expected result: 8

8. Test other tools:

   • subtract: {"a": 10, "b": 4} → 6
   • multiply: {"a": 5, "b": 3} → 15
   • divide: {"a": 15, "b": 3} → 5.0
   • divide (error test): {"a": 10, "b": 0} → Error: "Cannot divide by zero"

Using the Calculator Server with Claude

Option A: Claude Desktop Integration

To use the calculator server with Claude Desktop:

uv run mcp install calculator_server.py --name "Calculator"

This registers the server with Claude Desktop. Once installed, you can use the calculator tools in your Claude conversations by asking Claude to perform arithmetic operations.

Option B: Direct MCP Inspector Testing

uv run mcp dev calculator_server.py

This launches the MCP Inspector for interactive testing and development.

Server Capabilities

The MCP Calculator Server exposes three main types of MCP capabilities:

Tools (Calculator Functions)

The server provides the following arithmetic tools that can be called by MCP clients:

• add: Add two numbers together

  • Parameters: a (float), b (float)
  • Returns: Sum of a and b

• subtract: Subtract b from a

  • Parameters: a (float), b (float)
  • Returns: Difference (a - b)

• multiply: Multiply two numbers

  • Parameters: a (float), b (float)
  • Returns: Product of a and b

• divide: Divide a by b

  • Parameters: a (float), b (float)
  • Returns: Quotient (a / b)
  • Note: Returns an error if b is zero

Resources

The server provides the following resources that clients can read:

• MCP TypeScript SDK Documentation (resource://typescriptsdk)
  • MIME Type: text/markdown
  • Contains: Complete TypeScript SDK documentation for building MCP clients

Prompts

The server provides pre-written prompt templates that help users accomplish specific tasks:

• Meeting Analysis Template (meeting_analysis)
  • A comprehensive framework for analyzing meeting transcripts and generating executive summaries, detailed minutes, action items, and risk analysis
  • See Meeting Analysis Prompt Template section below for details

Meeting Analysis Prompt Template

Overview

The MCP Calculator Server includes a powerful Meeting Analysis prompt template that helps analyze meeting transcripts with exceptional attention to detail. This prompt is designed for executive assistants and business professionals who need to transform raw meeting transcripts into structured, actionable insights.

How to Use the Meeting Analysis Prompt

When you call the meeting_analysis prompt with your meeting details, it will guide you through a comprehensive analysis framework with five key sections:

Parameters:

• meeting_date (string): The date when the meeting took place (e.g., "January 30, 2026")
• meeting_title (string): The title or subject of the meeting (e.g., "Q1 Strategy Planning")
• transcript (string): The full transcript of the meeting

Example Usage in Claude Desktop:

Once the server is connected, you can request the prompt by saying something like:

"Please analyze this meeting using the meeting analysis template. The meeting was held on January 30, 2026, titled 'Strategic Planning Session', and here's the transcript: [paste transcript here]"

Analysis Output

The prompt will structure the analysis into five comprehensive sections:

1. Executive Summary - Overview of meeting purpose, strategic decisions, and critical insights
2. Detailed Minutes - Organized by topic with attendees, discussions, decisions, and action items
3. Key Decisions & Action Items - Enumerated decisions with clear responsibility assignments and deadlines
4. Risk Analysis - Identified risks, opportunities, and areas requiring further discussion
5. Individual Contributions - Summary of key points by each participant and their commitments

Template Principles

The meeting analysis template follows these professional guidelines:

• Objective and Factual: Captures what was actually discussed without bias
• Comprehensive: Captures both explicit and implicit information from the meeting
• Professional: Maintains appropriate business language and tone
• Strategic: Highlights strategic implications and business impact
• Actionable: Includes clear follow-up requirements and next steps

Project Structure

After setup, your project folder should look like:

your-project-folder/
├── .venv/                    # Virtual environment (created by uv venv)
│   ├── Scripts/              # Executable scripts (Windows)
│   ├── bin/                  # Executable scripts (macOS/Linux)
│   └── lib/                  # Python packages
├── calculator_server.py      # The MCP server code (the file you created)
├── README.md                 # This file
└── .gitignore                # (Optional) Git ignore file

Important folders:

• .venv/ - Virtual environment. Do NOT commit this to git
• calculator_server.py - Your MCP server implementation

Troubleshooting

Issue: Virtual environment won't activate

Solution: Ensure you're in the correct directory and the .venv folder exists.

# Check if .venv exists
ls .venv  # macOS/Linux
dir .venv  # Windows PowerShell

# If not, recreate it
uv venv

Issue: "mcp command not found"

Solution: Make sure the virtual environment is activated:

# Windows
.\.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

Then verify:

mcp --version

Issue: "Python not found"

Solution: Python isn't installed or not in PATH. Follow Step 1 to install Python and ensure "Add Python to PATH" is checked during installation (Windows).

Issue: "Permission denied" on macOS/Linux

Solution: You may need to make the script executable:

chmod +x calculator_server.py

Issue: Division by zero error

Solution: The server intentionally prevents division by zero. Use the divide tool with non-zero divisors.

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

Solution: Make sure the virtual environment is activated and MCP is installed:

# Verify you're in the virtual environment
# Your prompt should show (.venv)

# Reinstall MCP if needed
uv pip install "mcp[cli]"

Issue: Port already in use (if using HTTP transport)

Solution: The default stdio transport doesn't use ports. If you modified the server to use HTTP, kill the process using that port:

Windows:

netstat -ano | findstr :8000
taskkill /PID <PID> /F

macOS/Linux:

lsof -i :8000
kill -9 <PID>

Deactivating the Virtual Environment

When you're done working on the project:

deactivate

Your prompt will return to normal (without the (.venv) prefix).

To work on the project again, simply activate the virtual environment using Step 5.

Next Steps

1. Explore the MCP Specification: Visit modelcontextprotocol.io for more information

2. Try the Meeting Analysis Prompt: Use the new meeting_analysis prompt template to analyze meeting transcripts and generate professional summaries with structured insights

3. Add More Tools: Extend calculator_server.py with additional mathematical functions like:

   • Power: a ** b
   • Square root: math.sqrt(a)
   • Logarithm: math.log(a)
   • Trigonometric functions

4. Create Custom Prompts: Add your own prompt templates for domain-specific tasks (e.g., code review, document analysis, customer support templates)

5. Build Complex Servers: Learn to add resources and advanced features to create specialized MCP servers

6. Use with Clients: Connect to Claude, ChatGPT, or other MCP-compatible clients

7. Deploy Your Server: Learn about different transport options (HTTP, SSE, stdio)

Important Notes

• Always activate the virtual environment before running the server or installing packages
• Keep the virtual environment in your project folder (.venv) for easy management
• Never share your .venv folder - others can recreate it with uv venv and uv pip install "mcp[cli]"
• The server uses stdio transport by default, which works with MCP Inspector and clients
• All tools return structured output based on their type hints (floats, in this case)
• Tools support error handling - the divide function raises an exception on division by zero
• Prompts enable you to define structured templates and workflows that guide users through complex tasks (e.g., the Meeting Analysis template)
• The server exposes three types of MCP capabilities: Tools (callable functions), Resources (readable data), and Prompts (structured templates)

Resources

• Model Context Protocol Documentation
• MCP Python SDK Documentation
• MCP Specification
• uv Documentation
• Python Virtual Environments
• MCP Inspector

---

Congratulations! You now have a working MCP calculator server. Happy calculating! 🧮