# 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)
```json
{
"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:
```json
{
"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:
```json
{
"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:
```bash
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
```bash
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](#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.
```bash
# 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:
```bash
# Windows
.\.venv\Scripts\Activate.ps1
# macOS/Linux
source .venv/bin/activate
```
Then verify:
```bash
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:
```bash
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:
```bash
# 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:**
```powershell
netstat -ano | findstr :8000
taskkill /PID <PID> /F
```
**macOS/Linux:**
```bash
lsof -i :8000
kill -9 <PID>
```
## Deactivating the Virtual Environment
When you're done working on the project:
```bash
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](https://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](https://modelcontextprotocol.io/)
- [MCP Python SDK Documentation](https://modelcontextprotocol.github.io/python-sdk/)
- [MCP Specification](https://modelcontextprotocol.io/specification)
- [uv Documentation](https://docs.astral.sh/uv/)
- [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
---
**Congratulations!** You now have a working MCP calculator server. Happy calculating! 🧮
