Mashov MCP Server

An MCP (Model Context Protocol) server for interacting with the Mashov school management system API.

Features

• 📊 Get average of all grades
• 📈 Get all grades in graph format (optionally filtered by subject)
• 🎓 Get average of Bagrut (matriculation) grades
• 🏫 Get list of all schools
• 📸 Get user's profile picture
• 👥 Get user's class list
• 💬 Get messages
• 📅 Get schedule/timetable

Prerequisites

Choose one of the following:

Option 1: Docker (Recommended for Easy Setup) 🐳

• Docker installed (Get Docker)
• Mashov account credentials

Option 2: Python (For Development)

• Python 3.8 or higher
• uv (recommended) or pip
• Mashov account credentials

Installation

🐳 Option 1: Using Docker (Recommended)

1. Clone this repository:

git clone https://github.com/AmitMarcus/MashovMCP.git
cd MashovMCP

2. Build the Docker image (required before using with MCP):

docker build -t mashov-mcp-server:latest .

⚠️ Important: You must build the image before configuring your MCP client.

3. Verify the image was built:

docker images | grep mashov-mcp-server

You should see:

mashov-mcp-server   latest   ...   ...   ...

4. Test it (optional):

docker run -i --rm \
  -e MASHOV_USERNAME="your_username" \
  -e MASHOV_PASSWORD="your_password" \
  -e MASHOV_SEMEL="your_school_id" \
  -e MASHOV_YEAR="2025" \
  mashov-mcp-server:latest

🐍 Option 2: Using Python + uv

1. Clone this repository:

git clone https://github.com/AmitMarcus/MashovMCP.git
cd MashovMCP

2. Install uv (if not already installed):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install dependencies:

uv pip install -e .

4. Configure credentials:

cp env.example .env
# Edit .env with your Mashov credentials

Configuration

Create a .env file with your Mashov credentials:

MASHOV_USERNAME=your_username
MASHOV_PASSWORD=your_password
MASHOV_SEMEL=your_school_id
MASHOV_YEAR=2024

Usage

Testing the API (Without MCP)

Before using the MCP server, you can test the API client directly:

python test_api.py

This script will:

• Test authentication
• Test API endpoints
• Show detailed results
• Help debug API issues

This is useful for:

• Verifying your credentials work
• Debugging API endpoint issues
• Understanding the API response format
• Testing before integrating with MCP

Running the MCP Server

The server runs via stdio and communicates using the MCP protocol:

python mashov_mcp_server.py

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration file.

Option 1: Using Docker 🐳 (Recommended)

{
  "mcpServers": {
    "mashov": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MASHOV_USERNAME=your_username",
        "-e", "MASHOV_PASSWORD=your_password",
        "-e", "MASHOV_SEMEL=your_school_id",
        "-e", "MASHOV_YEAR=2025",
        "mashov-mcp-server:latest"
      ]
    }
  }
}

Option 2: Using Python 🐍

{
  "mcpServers": {
    "mashov": {
      "command": "python",
      "args": ["/absolute/path/to/MashovMCP/mashov_mcp_server.py"],
      "env": {
        "MASHOV_USERNAME": "your_username",
        "MASHOV_PASSWORD": "your_password",
        "MASHOV_SEMEL": "your_school_id",
        "MASHOV_YEAR": "2025"
      }
    }
  }
}

Available Tools

get_grades_average

Get the average of all grades for the authenticated user.

get_all_grades

Get all grades in graph format, optionally filtered by subject.

• Parameters:
  • subject (optional): Subject name to filter grades

get_bagrut_average

Get the average of all Bagrut (matriculation) grades.

get_schools

Get list of all available schools.

get_user_picture

Get the authenticated user's profile picture.

get_class_list

Get the user's class list.

get_messages

Get messages for the authenticated user.

• Parameters:
  • limit (optional): Maximum number of messages to retrieve (default: 10)

get_schedule

Get the user's schedule/timetable.

Project Structure

MashovMCP/
├── mashov_mcp_server.py      # Main MCP server implementation
├── mashov_client.py          # Mashov API client wrapper
├── config.py                 # Configuration handling
├── pyproject.toml            # Project metadata and dependencies (uv/pip)
├── Dockerfile                # Docker image definition
├── .dockerignore             # Docker build exclusions
├── test_api.py               # API test script
├── .gitignore                # Git ignore rules
├── env.example               # Example environment configuration
├── AUTHENTICATION.md         # Authentication flow documentation
├── LICENSE                   # MIT License
└── README.md                 # This file

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.