Math Quiz with MCP Server

A demonstration application showing how an MCP (Model Context Protocol) server can act as a mathematical coprocessor. The LLM decides what calculations to perform, and the MCP server handles the computation using mathjs.

Architecture

Frontend: React + Vite + Tailwind CSS - Simple math quiz interface
MCP Server: Node.js + TypeScript - Mathematical evaluation service

Project Structure

mcp-math/ ├── frontend/ # React quiz application │ ├── src/ │ │ ├── App.tsx # Main quiz component │ │ ├── main.tsx # React entry point │ │ └── index.css # Tailwind styles │ └── package.json ├── mcp-server/ # MCP server for math operations │ ├── src/ │ │ └── index.ts # MCP server implementation │ └── package.json └── package.json # Workspace root

Setup Instructions

1. Install Dependencies

From the root directory:

npm install cd frontend && npm install cd ../mcp-server && npm install cd ..

Or use the convenience script:

npm run install:all

2. Build the MCP Server

cd mcp-server npm run build

3. Configure MCP Client

For Cursor

Add the MCP server to your Cursor configuration file:

Location: ~/.cursor/mcp.json

Example configuration:

{ "mcpServers": { "math": { "command": "node", "args": ["${HOME}/path/to/mcp-math/mcp-server/dist/index.js"] } } }

Important: Replace path/to/mcp-math with the actual path from your home directory to your project directory. The ${HOME} variable will be automatically expanded.

After updating the configuration, restart Cursor for the changes to take effect.

For Claude Desktop

Add the MCP server to your Claude Desktop configuration file:

MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Example configuration:

{ "mcpServers": { "math": { "command": "node", "args": ["${HOME}/path/to/mcp-math/mcp-server/dist/index.js"] } } }

Important: Replace path/to/mcp-math with the actual path from your home directory to your project directory.

After updating the configuration, restart Claude Desktop for the changes to take effect.

Running the Application

Start the Frontend

cd frontend npm run dev

The quiz app will be available at http://localhost:5173

Using the MCP Server with Claude/Cursor

Once configured, you can ask Claude (or Cursor AI) to use the math server:

Example prompts:

"Use the math server to calculate 123 * 456"
"Evaluate sqrt(144) + sin(pi/2) using the evaluate tool"
"What is (25 + 75) / (10 - 5)?"

The AI will automatically use the evaluate tool from the MCP server to perform calculations.

MCP Server Tools

`evaluate`

Evaluates a mathematical expression and returns the result.

Input:

expression (string): Mathematical expression to evaluate

Supported Operations:

Basic arithmetic: +, -, *, /
Exponents: ^ or **
Parentheses: (, )
Common functions: sqrt(), sin(), cos(), tan(), log(), etc.
Constants: pi, e

Example:

{ "expression": "2 * (3 + 4)" }

Response:

{ "expression": "2 * (3 + 4)", "result": "14", "success": true }

Development

Frontend Development

npm run dev:frontend

MCP Server Development

After making changes to the MCP server:

cd mcp-server npm run build

Then restart Claude Desktop to load the updated server.

Build for Production

# Build frontend npm run build:frontend # Build MCP server npm run build:mcp

How It Works

The MCP Pattern

This application demonstrates the "coprocessor" pattern:

Frontend displays math problems to users
LLM (Claude) understands user intent and decides what calculations to perform
MCP Server executes the calculations accurately using mathjs
Result flows back through Claude to the application

Why Use MCP for Math?

Accuracy: LLMs can struggle with precise calculations. The MCP server uses mathjs for exact results.
Separation of Concerns: The LLM focuses on understanding and orchestration, while the MCP server handles computation.
Extensibility: Easy to add new mathematical operations without retraining the model.

Notes

The current frontend implementation calculates answers locally for demo simplicity
In a production setup, you would connect the frontend to Claude (via API or desktop app) which would use the MCP server
This is a demonstration project showing MCP architecture - not production-ready

Future Enhancements

Potential improvements:

Add database for storing quiz results
Connect frontend directly to Claude API with MCP
Add more quiz types (algebra, geometry, etc.)
Implement user authentication and progress tracking
Add difficulty levels and adaptive quizzing

Troubleshooting

MCP Server not showing in Claude/Cursor

Check the configuration file path is correct (~/.cursor/mcp.json for Cursor)
Ensure the path to index.js is correct (use ${HOME}/... for portability)
Verify the server builds without errors: cd mcp-server && npm run build
Check logs:
- Claude Desktop: Help → Show Logs
- Cursor: Check the MCP server output in Cursor settings
Restart Claude Desktop or Cursor after configuration changes

Frontend not starting

Ensure dependencies are installed: cd frontend && npm install
Check Node.js version (requires Node 18+)
Try clearing node_modules and reinstalling

License

MIT

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables LLMs to perform accurate mathematical calculations by evaluating expressions using mathjs. Supports basic arithmetic, functions, constants, and complex mathematical operations through natural language requests.

Math MCP Server