Powerschool

A FastMCP server for PowerSchool that enables students to check grades, assignments, grade history, and attendance through the Model Context Protocol.

Deploy to Render

Features

This MCP server provides the following tools for students:

• get_student_info: Get current student information (name, ID, grade level, school)
• get_current_grades: View current grades for all courses
• get_assignments: List assignments (optionally filter by course)
• get_grade_history: View historical grade data with date filtering
• get_courses: List all enrolled courses/sections
• get_attendance: View attendance records
• get_server_info: Check server configuration and status

Configuration

Required Environment Variables

You need to configure the following environment variables to connect to your PowerSchool instance:

# PowerSchool server URL (without trailing slash)
POWERSCHOOL_URL=https://your-school.powerschool.com

# OAuth2 Client Credentials from PowerSchool Plugin
POWERSCHOOL_CLIENT_ID=your_client_id
POWERSCHOOL_CLIENT_SECRET=your_client_secret

# Student Authentication (for password grant type)
POWERSCHOOL_USERNAME=student_username
POWERSCHOOL_PASSWORD=student_password

PowerSchool Setup

This server requires a PowerSchool plugin with OAuth2 enabled. Your PowerSchool administrator needs to:

1. Install a PowerSchool plugin with <oauth/> enabled in plugin.xml
2. Configure API permissions for student data access
3. Generate OAuth2 client credentials (client ID and secret)
4. Enable the necessary API endpoints:
   • /ws/v1/student - Student information
   • /ws/v1/student/grades - Grade data
   • /ws/v1/student/assignments - Assignment data
   • /ws/v1/student/sections - Course/section data
   • /ws/v1/student/attendance - Attendance data

For more information about PowerSchool's API, see:

• PowerSchool API Documentation
• Reverse-engineered API Reference

Local Development

Setup

Fork the repo, then run:

git clone <your-repo-url>
cd mcp-powerschool
conda create -n mcp-powerschool python=3.13
conda activate mcp-powerschool
pip install -r requirements.txt

Configure Environment Variables

Create a .env file or set environment variables:

export POWERSCHOOL_URL=https://your-school.powerschool.com
export POWERSCHOOL_CLIENT_ID=your_client_id
export POWERSCHOOL_CLIENT_SECRET=your_client_secret
export POWERSCHOOL_USERNAME=your_username
export POWERSCHOOL_PASSWORD=your_password

Test Locally

python src/server.py
# then in another terminal run:
npx @modelcontextprotocol/inspector

Open http://localhost:3000 and connect to http://localhost:8000/mcp using "Streamable HTTP" transport (NOTE THE /mcp!).

Available Tools

Once connected, you can test the following tools:

1. get_server_info - Verify configuration
2. get_student_info - Get student details
3. get_current_grades - View all current grades
4. get_courses - List enrolled courses
5. get_assignments - View assignments (optional: pass section_id)
6. get_grade_history - View historical grades (optional: pass start_date, end_date)
7. get_attendance - View attendance records

Deployment

Option 1: One-Click Deploy to Render

1. Click the "Deploy to Render" button above
2. Configure the required environment variables in Render's dashboard:
   • POWERSCHOOL_URL
   • POWERSCHOOL_CLIENT_ID
   • POWERSCHOOL_CLIENT_SECRET
   • POWERSCHOOL_USERNAME
   • POWERSCHOOL_PASSWORD

Option 2: Manual Deployment

1. Fork this repository
2. Connect your GitHub account to Render
3. Create a new Web Service on Render
4. Connect your forked repository
5. Render will automatically detect the render.yaml configuration
6. Add the required environment variables in Render's dashboard

Your server will be available at https://your-service-name.onrender.com/mcp (NOTE THE /mcp!)

Usage with AI Assistants

You can connect this MCP server to various AI assistants that support the Model Context Protocol:

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "powerschool": {
      "url": "https://your-service-name.onrender.com/mcp"
    }
  }
}

Poke

You can connect your MCP server to Poke at poke.com/settings/connections.

To test the connection explicitly, ask poke something like: Tell the subagent to use the "powerschool" integration's "get_current_grades" tool.

If you run into persistent issues of poke not calling the right MCP (e.g. after you've renamed the connection), you may send clearhistory to poke to delete all message history and start fresh.

Example Usage

Here are some example queries you can make through your AI assistant:

• "What are my current grades?"
• "Show me my assignments for math class"
• "What's my attendance record this semester?"
• "How have my grades changed over the last month?"
• "List all my courses and teachers"
• "Show me my student information"

API Reference

PowerSchool API Endpoints

This server uses the PowerSchool REST API. The main endpoints are:

• GET /ws/v1/student - Get student information
• GET /ws/v1/student/grades - Get current grades
• GET /ws/v1/student/assignments - Get all assignments
• GET /ws/v1/student/assignments/section/{id} - Get assignments for a section
• GET /ws/v1/student/sections - Get enrolled sections/courses
• GET /ws/v1/student/attendance - Get attendance records
• GET /ws/v1/student/grades/history - Get historical grades

Authentication

The server uses OAuth2 for authentication with PowerSchool. It supports both:

1. Client Credentials Grant - For server-to-server authentication
2. Password Grant - For student username/password authentication

The authentication token is automatically cached and refreshed as needed.

Security Notes

⚠️ Important Security Considerations:

1. Credentials Storage: Store credentials securely using environment variables or secret management services. Never commit credentials to version control.

2. HTTPS: Always use HTTPS in production to protect credentials and student data in transit.

3. Access Control: This server is designed for individual student use. Each deployment should be configured with credentials for a single student.

4. Token Security: Authentication tokens are cached in memory and automatically refreshed. They are never persisted to disk.

5. Production Deployment: When deploying to production, ensure your hosting platform (like Render) properly secures environment variables.

Troubleshooting

Configuration Issues

If you get configuration errors, verify:

• All required environment variables are set
• PowerSchool URL doesn't have a trailing slash
• Client ID and secret are correct
• Student credentials are valid (if using password grant)

Connection Issues

If the server can't connect to PowerSchool:

• Verify PowerSchool URL is accessible
• Check that the PowerSchool plugin is installed and OAuth is enabled
• Ensure API endpoints are enabled for student access
• Check firewall rules if running on-premises

Authentication Issues

If authentication fails:

• Verify client credentials are correct
• Check that student username/password are valid
• Ensure the OAuth2 grant type (password or client_credentials) is enabled

Use the get_server_info tool to check configuration status.

Development

Adding New Tools

You can add more PowerSchool API endpoints by:

1. Adding a method to the PowerSchoolAPI class
2. Creating a corresponding MCP tool with @mcp.tool decorator
3. Following the existing pattern for error handling and response format

Example:

@mcp.tool(description="Get school calendar events")
def get_calendar() -> dict:
    try:
        client = get_api_client()
        result = client._make_request("/ws/v1/student/calendar")
        return {
            "success": True,
            "data": result
        }
    except Exception as e:
        return {
            "success": False,
            "error": str(e)
        }

License

This project is open source and available under the MIT License.

Contributing

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

Support

For issues related to:

• This MCP Server: Open an issue on GitHub
• PowerSchool API: Contact PowerSchool support or your school administrator
• MCP Protocol: See Model Context Protocol Documentation