GeoGebra MCP Tool

A Model Context Protocol (MCP) server that enables AI models to interact with GeoGebra's mathematical software suite for creating interactive mathematical visualizations and dynamic constructions.

🎯 Overview

The GeoGebra MCP Tool bridges the gap between AI reasoning capabilities and mathematical visualization, allowing AI assistants to:

• Create geometric constructions (points, lines, circles, polygons)
• Plot mathematical functions and graphs
• Perform algebraic computations with visual representation
• Generate interactive mathematical demonstrations
• Export visualizations in various formats

🚀 Quick Start Examples

1. NPX (Recommended):

# Start the server
npx @gebrai/gebrai

# Or with custom log level
npx @gebrai/gebrai --log-level debug

1. Connect to Claude Desktop - Add to your Claude configuration:

{
  "mcpServers": {
    "geogebra": {
      "command": "npx",
      "args": ["@gebrai/gebrai"]
    }
  }
}

1. Start Creating - Ask Claude to create mathematical visualizations!

Need help? Check our Getting Started Guide for detailed instructions.

📦 Installation Options

NPX (No Installation)

npx @gebrai/gebrai

✅ No installation required
✅ Always uses latest version
✅ Perfect for testing

Global Installation

npm install -g @gebrai/gebrai

✅ Faster startup after installation
✅ Works offline
✅ Consistent version

Local Development

git clone <repository-url>
cd gebrai && npm install

✅ Full source code access
✅ Customization possible
✅ Development workflow

🛠️ CLI Usage

The GeoGebra MCP Tool provides a command-line interface with the following options:

Usage:
  npx @gebrai/gebrai [options]
  gebrai [options]              # if installed globally
  geogebra-mcp [options]        # alternative command

Options:
  -h, --help        Show help message
  -v, --version     Show version information
  --log-level LEVEL Set log level (error, warn, info, debug) [default: info]
  --port PORT       Set server port [default: stdin/stdout for MCP]

Examples:
  npx @gebrai/gebrai                    # Start MCP server
  npx @gebrai/gebrai --log-level debug  # Start with debug logging
  npx @gebrai/gebrai --help             # Show help

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager

Installation

1. Clone the repository:

git clone <repository-url>
cd gebrai

1. Install dependencies:

npm install

1. Build the project:

npm run build

1. Start the server:

npm start

Development Mode

For development with hot reload:

npm run dev

🛠️ Development

Project Structure

gebrai/
├── src/
│   ├── index.ts          # Main entry point
│   ├── server.ts         # MCP server implementation
│   ├── types/
│   │   └── mcp.ts        # MCP protocol types
│   ├── tools/
│   │   └── index.ts      # Tool registry and example tools
│   └── utils/
│       ├── logger.ts     # Logging utility
│       └── errors.ts     # Error handling
├── tests/
│   ├── setup.ts          # Test configuration
│   └── server.test.ts    # Server tests
├── package.json
├── tsconfig.json
└── README.md

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build the TypeScript project
• npm start - Start the production server
• npm test - Run the test suite
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint issues automatically

Testing

The project includes a comprehensive test suite using Jest:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

📚 Documentation

For comprehensive documentation, visit our complete documentation which includes:

📖 Core Documentation

• API Reference - Complete tool documentation with examples
• Getting Started Guide - Step-by-step setup and first usage
• Integration Guide - Platform integration instructions
• Troubleshooting - Common issues and solutions
• FAQ - Frequently asked questions

🔧 Tool Categories

• Basic Tools - Core MCP functionality (ping, echo, server_info)
• GeoGebra Tools - 25+ mathematical construction tools
• Educational Tools - Pre-built educational templates
• Performance Tools - Monitoring and optimization

🎓 Educational Resources

• Use Cases - Real-world educational scenarios
• Teacher Guide - Pedagogical guidance
• Classroom Examples - Ready-to-use lessons

📝 Tutorials & Examples

• Basic Usage - Your first mathematical constructions
• Mathematical Constructions - Geometry and algebra
• Function Plotting - Creating mathematical functions
• Code Examples - Working examples by complexity

📊 Tool Overview

The GeoGebra MCP Tool provides 40+ tools across four categories:

Example Tools

• Mathematical: geogebra_create_point, geogebra_plot_function, geogebra_export_png
• Educational: geogebra_list_educational_templates, geogebra_create_lesson_plan
• Performance: performance_get_stats, performance_warm_up_pool

🔧 Configuration

Environment Variables

• PORT - Server port (default: 3000)
• LOG_LEVEL - Logging level: error, warn, info, debug (default: info)
• NODE_ENV - Environment: development, production, test

Example .env file

PORT=3000
LOG_LEVEL=info
NODE_ENV=development

🏗️ Architecture

Core Components

1. MCP Server (src/server.ts)

   • Handles JSON-RPC 2.0 protocol
   • Routes requests to appropriate handlers
   • Manages server lifecycle

2. Tool Registry (src/tools/index.ts)

   • Manages available tools
   • Handles tool execution
   • Provides tool discovery

3. Error Handling (src/utils/errors.ts)

   • Standardized error responses
   • JSON-RPC error codes
   • Comprehensive error logging

4. Logging (src/utils/logger.ts)

   • Structured logging with Winston
   • Configurable log levels
   • Development and production modes

Design Principles

• Type Safety: Full TypeScript implementation with strict mode
• Error Handling: Comprehensive error handling and validation
• Modularity: Clean separation of concerns
• Testability: Extensive test coverage
• Extensibility: Easy to add new tools and features

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-tool
3. Make your changes and add tests
4. Ensure all tests pass: npm test
5. Commit your changes: git commit -m 'Add new tool'
6. Push to the branch: git push origin feature/new-tool
7. Submit a pull request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new functionality
• Update documentation as needed
• Use conventional commit messages
• Ensure code passes linting

🔗 Related Projects

• Model Context Protocol
• GeoGebra
• JSON-RPC 2.0 Specification

📞 Support

For questions, issues, or contributions, please:

1. Check the Issues page
2. Create a new issue if needed
3. Join our community discussions