SchoolFinance MCP Server

A production-grade Model Context Protocol server for SchoolFinance, a single-user desktop school finance application. It exposes the entire school finance domain — students, classes, payments, income/expenses, reports, settings, notifications and a recycle bin — as MCP tools and resources, backed by a local SQLite database.

• Single administrator (school owner), full access, no authentication
• Synchronous SQLite via better-sqlite3 — no server, no runtime surprises
• Zod-validated tool inputs and resource data
• Structured JSON responses ({ success, data } / { success, error })
• Soft deletes + recycle bin + audit log
• CSV and JSON export

Tech stack

Piece	Choice
Language	TypeScript (strict), ESModules
MCP SDK	@modelcontextprotocol/sdk (McpServer)
Transport	stdio (spec-compliant JSON-RPC messages)
Database	SQLite file (schoolfinance.db) + better-sqlite3
Validation	zod v3

Getting started

npm install
npm run build        # compile TypeScript to dist/
npm start            # run the compiled server (stdio)

For development you can run the server directly with tsx:

npm run dev

The server speaks MCP over stdio, so it is driven by an MCP client. In an MCP client config:

{
  "mcpServers": {
    "school-finance": {
      "command": "node",
      "args": ["/path/to/school-finance-mcp/dist/index.js"],
      "env": { "DB_PATH": "/path/to/schoolfinance.db" }
    }
  }
}

Configuration

All configuration is via environment variables (see .env.example):

Variable	Default	Description
DB_PATH	./schoolfinance.db	SQLite database file location
BACKUP_DIR	./backups	Where backup_database writes files
LOG_LEVEL	info	debug | info | warn | error

Logs are written to stderr (MCP best practice) so the stdout protocol stream stays clean.

Tools

Dashboard

• get_dashboard_stats — counts, outstanding balance, monthly revenue/expenses, recent activity
• get_recent_activity — last 10 audit-log entries
• get_financial_summary — month income/expenses/balance plus previous-month trend

Students

• create_student / update_student / delete_student (soft) / restore_student
• get_student — detail incl. payments + balance
• search_students / list_students — query, filters, sort, pagination

Classes

• create_class / update_class / delete_class / assign_student_to_class / list_classes

Payments

• record_payment / edit_payment / delete_payment (soft)
• get_payment_history / get_unpaid_students / get_overdue_students / get_student_balance

Income & Expenses

• add_income / add_expense / update_transaction / delete_transaction
• get_transaction_history / get_monthly_summary

Reports

• generate_financial_report / generate_student_balance_report / generate_class_report
• export_data — CSV or JSON for any resource

Settings

• update_school_info / manage_payment_templates / set_academic_year
• backup_database / restore_database

Notifications

• get_pending_reminders / mark_reminder_completed

Recycle Bin

• list_deleted_items / restore_deleted_item / permanently_delete_item

Resources

The schoolfinance://* namespace exposes live data:

schoolfinance://dashboard
schoolfinance://students
schoolfinance://classes
schoolfinance://payments
schoolfinance://income
schoolfinance://expenses
schoolfinance://reports
schoolfinance://settings
schoolfinance://notifications
schoolfinance://recycle-bin

Domain rules

• A student's balance = class fee − total active payments. Balances are recalculated whenever payments or class fees change.
• Overdue = outstanding balance and enrolment older than 30 days (documented heuristic for this single-user app).
• Deleting a class with enrolled students is blocked — reassign students first.
• delete_student, delete_payment and delete_transaction are soft deletes; items appear in the recycle bin.
• income/expenses carry a deleted_at column (slightly beyond the spec's table list) because they are soft-deletable and recyclable.

Database

Schema is created idempotently on startup. Tables: classes, students, payments, income, expenses, settings, notifications, audit_log. WAL mode is enabled for durability and concurrent access safety.

Testing

npm test          # spawns the server and speaks real MCP over stdio

Tests use a throwaway database in the OS temp directory (see tests/setup.ts).

Project structure

src/
├── index.ts              # entry point
├── server.ts             # McpServer assembly, tool + resource registration
├── config/database.ts    # SQLite connection + schema
├── services/             # business logic (audit, students, classes, payments, ...)
├── schemas/              # Zod schemas for inputs and resource data
├── resources/templates/  # report template
├── utils/                # db, date, export, logging, response helpers
└── tools/                # MCP tool registrations

Connecting to MCP Clients

The server runs as a stdio process — the client spawns it, sends JSON-RPC messages over stdin, and reads responses from stdout. Below are step-by-step instructions for each client.

Prerequisites

Build the server first:

npm install
npm run build          # compiles to dist/index.js

Find the absolute path:

realpath dist/index.js   # e.g. /home/user/mcp-schoolfinance/dist/index.js
realpath schoolfinance.db # (or create a persistent DB path)

Claude Desktop

1. Edit claude_desktop_config.json:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the server:

{
  "mcpServers": {
    "school-finance": {
      "command": "node",
      "args": ["/absolute/path/to/school-finance-mcp/dist/index.js"],
      "env": {
        "DB_PATH": "/absolute/path/to/school-finance.db"
      }
    }
  }
}

3. Restart Claude Desktop. The server will appear in Claude's MCP settings.

Claude Code (CLI / VS Code extension)

1. Edit .opencode.jsonc or .claude.json in your project root:

{
  "mcp": {
    "school-finance": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/school-finance-mcp/dist/index.js"],
      "env": { "DB_PATH": "/absolute/path/to/school-finance.db" }
    }
  }
}

2. Or add to ~/.config/.opencode/mcp.json for all projects.

Cursor

1. Open Settings → Cursor Settings → MCP tab (or search "MCP")
2. Click "Add MCP Server"
3. Enter:
   • Name: school-finance
   • Type: stdio
   • Command: node /absolute/path/to/school-finance-mcp/dist/index.js
   • Environment Variables: add DB_PATH → /absolute/path/to/school-finance.db

ChatGPT (Desktop / web with ChatGPT Pro)

ChatGPT's desktop app supports MCP via mcp_config.json:

1. Edit ~/.chatgpt/mcp_config.json (or the config path shown in-app)
2. Add:

{
  "mcpServers": {
    "school-finance": {
      "command": "node",
      "args": ["/absolute/path/to/school-finance-mcp/dist/index.js"],
      "env": { "DB_PATH": "/absolute/path/to/school-finance.db" }
    }
  }
}

3. Restart the ChatGPT desktop app.

VS Code (with MCP extension)

1. Install the modelcontextprotocol.mcp extension (or use Claude/Copilot with MCP support)
2. Edit .vscode/mcp.json:

{
  "servers": {
    "school-finance": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/school-finance-mcp/dist/index.js"],
      "env": { "DB_PATH": "/absolute/path/to/school-finance.db" }
    }
  }
}

Using with OpenCode

Add to your OpenCode configuration to let the agent use SchoolFinance tools:

// ~/.config/opencode/opencode.jsonc
{
  "mcp": [
    {
      "name": "school-finance",
      "command": "node /absolute/path/to/school-finance-mcp/dist/index.js",
      "env": { "DB_PATH": "/absolute/path/to/school-finance.db" }
    }
  ]
}

Available Tools

Once connected, AI assistants can call these tools, for example:

# Create a class and add students
create_class(name="Grade 10A", year_level=10, fee_amount=1200, description="Morning class")
create_student(name="Ahmed Hassan", email="ahmed@example.com", phone="+252612345678", 
  address="Mogadishu, Somalia", class_id=1, enrollment_date="2025-09-01")

# Record a payment
record_payment(student_id=1, amount=500, payment_date="2025-09-15", 
  method="cash", reference="REC-001", notes="Partial payment")

# Check student balance
get_student_balance(student_id=1)

# Generate reports
generate_financial_report(start_date="2025-01-01", end_date="2025-12-31")
export_data(resource="students", format="csv")

Troubleshooting

Problem	Fix
Server doesn't appear	Check absolute paths in config, ensure npm run build was run
Database errors	Ensure DB_PATH points to a writable directory, or omit to use ./schoolfinance.db
"Cannot find module"	Run npm install in the project directory
Logs not visible	MCP clients may suppress stderr; check the client's log viewer
Port/resource conflicts	SQLite is file-based, no port conflicts — ensure the DB file is accessible

License

MIT