How do I use PH Schools MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PH Schools MCP Server search for schools in Quezon City" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

PH Schools MCP Server

by darwinphi

Overview Schema Related Servers Score Discussions

JavaScript

Local

PH Schools MCP Server

Local stdio MCP server for querying and analyzing the Philippine schools masterlist dataset.

What This Server Provides

Tools:

search_schools
get_school_by_beis_id
list_regions
list_divisions
dataset_stats

Related MCP server: Skolverket MCP Server

Install and Run

npm install
npm start

Use npm start only when running from this repo manually.

Which Setup to Use

VS Code MCP (.vscode/mcp.json): enough for normal usage. If status is Running, VS Code already started the server.
Claude Desktop (claude_desktop_config.json): enough for normal usage. Restart Claude after config changes.
npx -y @darwinphi/ph-schools-mcp-server ...: one-off CLI usage without cloning repo.
npm install && npm start: local development/maintenance in this repository.

Usage Scenarios

mcp.json configured, no manual npx: works for chat tool calls (dataset_stats, search_schools, etc.).
Manual npx -y @darwinphi/ph-schools-mcp-server, no MCP client config: server process starts, but chat clients won't use it automatically.
mcp.json configured plus manual npx start: usually unnecessary; let the MCP client manage start/stop.
One-off commands without MCP chat: use npx ... --help or npx ... sync-data ....

Without MCP client config, automatic VS Code/Claude tool-calling will not work.

When to Use `mcp.json`

Use mcp.json for normal day-to-day MCP usage in VS Code (or equivalent client config in Claude Desktop).

Use it for:

Automatic server startup and lifecycle management by the MCP client
MCP tool usage directly from chat prompts (dataset_stats, search_schools, etc.)
Team/project-level shared MCP setup in a workspace

If MCP status shows Running, the client already started the server; manual npm start or manual npx start is usually unnecessary.

When to Use `npx`

Use npx from a terminal when you need one-off CLI actions without cloning or developing this repo.

Use it for:

Sanity check that the published package runs: npx -y @darwinphi/ph-schools-mcp-server --help
Manual dataset download/update: npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"
Manual debug startup outside client-managed MCP lifecycle: npx -y @darwinphi/ph-schools-mcp-server

Do not use npx start as a replacement for VS Code/Claude MCP config. In normal usage, let the MCP client manage server startup from its config.

When to Use `npm install` and `npm start`

Use these when working from this repository (developer/maintainer workflow), not for normal client usage.

Use them for:

Local development while editing source files in this repo
Running tests before commits/releases
Debugging local unpublished changes

Typical local workflow:

npm install
npm test
npm start

If your VS Code/Claude MCP config is already working, you usually do not need to run npm start manually.

CLI (published package)

# Start MCP server over stdio
npx -y @darwinphi/ph-schools-mcp-server

# Sync canonical dataset once to a chosen path
npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"

Quick Verify

npx -y @darwinphi/ph-schools-mcp-server --help
npx -y @darwinphi/ph-schools-mcp-server sync-data --tag v1.0.1 --output "$HOME/.ph-schools/data.json"

Dataset Configuration

This server is hybrid by default:

If local dataset file exists, it uses that file immediately.
If local dataset file is missing, it auto-downloads from the canonical dataset URL and caches locally.

Default canonical URL (pinned tag v1.0.1):

https://raw.githubusercontent.com/darwinphi/ph-schools-dataset/v1.0.1/schools_masterlist_2020_2021.json

Runtime env vars:

PH_SCHOOLS_DATA_PATH: preferred local JSON file path (used directly if present; auto-synced to this path if missing)
PH_SCHOOLS_DATA_URL: override download URL for sync-data
PH_SCHOOLS_DATA_TAG: canonical tag for sync-data when URL is not provided

VS Code MCP Config (Copy/Paste)

Set .vscode/mcp.json:

{
  "servers": {
    "phSchools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@darwinphi/ph-schools-mcp-server"],
      "env": {
        "PH_SCHOOLS_DATA_PATH": "/Users/your-user/.ph-schools/data.json"
      }
    }
  }
}

If PH_SCHOOLS_DATA_PATH file is missing, the server automatically downloads from canonical source and writes to that path.

Claude Desktop Config (Copy/Paste)

Update Claude config:

{
  "mcpServers": {
    "ph-schools": {
      "command": "npx",
      "args": ["-y", "@darwinphi/ph-schools-mcp-server"],
      "env": {
        "PH_SCHOOLS_DATA_PATH": "/Users/your-user/.ph-schools/data.json"
      }
    }
  }
}

Alternative if npx is unreliable in your shell: install globally and use "command": "ph-schools-mcp-server".

If PH_SCHOOLS_DATA_PATH file is missing, the server automatically downloads from canonical source and writes to that path.

Typical macOS config file:

~/Library/Application Support/Claude/claude_desktop_config.json

Test Commands

npm test
npm run test:package

Example Prompts

Run dataset_stats and summarize key insights.
List all divisions in Region I using list_divisions.
Search schools in region "Region I" and division "Ilocos Norte".
Get school by BEIS ID 100001 using get_school_by_beis_id.
Search schools with query "High School".

Publishing and Release Flow

One-time npm setup (Trusted Publishing):

On npmjs.com, open package @darwinphi/ph-schools-mcp-server → Settings → Trusted publishers.
Add GitHub Actions trusted publisher with:
- Owner/User: darwinphi
- Repository: ph-schools-mcp-server
- Workflow filename: cd.yml
Do not use NPM_TOKEN; release workflow uses OIDC (id-token: write).

Manual release flow (v1):

Update pinned dataset tag in src/constants.js.
Bump package version:

npm version patch   # or minor / major

What npm version patch does:

Updates package.json version (e.g., 1.0.1 -> 1.0.2)
Updates package-lock.json version fields
Creates a git commit
Creates a git tag (e.g., v1.0.2)

Sync server.json version to match package.json.
Run:

npm ci
npm test
npm run test:package

Push commit and tags:

git push
git push --tags

Create GitHub Release notes from the tag:

gh release create v<new_version> --generate-notes --title "v<new_version>"

Example:

gh release create v1.0.2 --generate-notes --title "v1.0.2"

Push commit and tags. Tag pushes (v*) automatically trigger CD Release workflow.
Workflow publishes npm package, then publishes MCP Registry metadata.

For metadata-only updates, use workflow Publish MCP Registry Metadata.

License and Data Provenance

Code license: ISC (LICENSE).
Dataset source: darwinphi/ph-schools-dataset (canonical repository backed by gov.ph source data).
Use of dataset remains subject to source terms and applicable policies.

Available Tools

5 tools

dataset_statsA

Return basic dataset stats and top-level breakdowns.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry full burden. It only says 'Return' which implies read-only, but does not disclose any behavioral traits such as safety, rate limits, or side effects. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single concise sentence, front-loaded with key information. It could be slightly more structured by listing types of stats, but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and a simple purpose, the description provides minimal context. It does not elaborate on what constitutes 'basic stats' or 'breakdowns', leaving room for ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; schema coverage is 100%. Baseline score is 4 per guidelines. Description adds no extra meaning, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool returns dataset stats and top-level breakdowns, with a specific verb ('Return') and resource. It is distinct from siblings which focus on schools, divisions, regions, and searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or alternatives. The description implies usage for obtaining dataset stats, but lacks exclusions or context for when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_school_by_beis_idA

Get one school record by BEIS School ID.

ParametersJSON Schema

Name	Required	Description	Default
`beis_school_id`	Yes	BEIS School ID, e.g., 100001

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It accurately states the operation but does not disclose any behavioral details such as error handling, return format, or assumptions (e.g., that the ID must exist). This is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded and to the point, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool with no output schema, the description is adequate but could benefit from stating what fields are returned or typical response behavior. It is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for the single parameter, so the description adds no new information beyond what the schema already provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The tool name 'get_school_by_beis_id' and description 'Get one school record by BEIS School ID' clearly specify the verb (Get), resource (school record), and identifier (BEIS School ID), distinguishing it from siblings like 'search_schools'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., search_schools) or when not to use it. The context of requiring a specific ID is implied but not stated as exclusive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_divisionsB

List divisions, optionally filtered by region.

ParametersJSON Schema

Name	Required	Description	Default
`region`	No	Region filter, e.g., Region I

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description must carry all behavioral info. It does not disclose whether unfiltered returns all divisions, pagination, authentication, or rate limits. The behavioral disclosure is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with no wasted words. Front-loaded with the core purpose. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a simple tool with one optional parameter and no output schema, the description is just adequate. Could mention match behavior (exact, partial) or typical response structure, but not critically incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'region'. The description adds 'optionally filtered by region', aligning with schema but not adding extra meaning beyond what 'Region filter, e.g., Region I' already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List divisions' with optional region filtering. The verb 'list' and resource 'divisions' are specific, and the sibling tools (e.g., list_regions, search_schools) help differentiate, though not explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. No mention of context, prerequisites, or exclusion criteria. The description only states that filtering is optional.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_regionsA

List all unique regions in the dataset.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies a read-only operation that returns unique regions. Without annotations, it adequately discloses the tool's behavior for a simple list function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 5 words with no redundancy. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description fully explains that it lists all unique regions in the dataset.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so baseline is 4. The description adds no parameter info, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all unique regions in the dataset.' It uses a specific verb (list) and resource (regions) and distinguishes from sibling tools like list_divisions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_schoolsB

Search PH schools by optional query fields (name, region, division, municipality, barangay, sector).

ParametersJSON Schema

Name	Required	Description
`query`	No	Free text match against school name and street address.
`region`	No	Region name (e.g., Region I).
`division`	No	Division name (e.g., Ilocos Norte).
`municipality`	No	Municipality name.
`barangay`	No	Barangay name.
`sector`	No	Public or Private.
`limit`	No	Max results (default 20, max 100).

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description does not explicitly state it is read-only or detail any side effects. As a search operation, read-only is implied but not confirmed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, clear and front-loaded with main verb and resource. Slightly wordy but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no description of return format, pagination, or default behavior (limit param described only in schema). For a search tool with 7 optional params, more context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage for all 7 parameters; description lists field names but adds no additional semantic meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Search PH schools' with optional query fields, distinguishing it from sibling tools like get_school_by_beis_id (specific ID lookup) and list_divisions (list data).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for general school search with optional fields, but no explicit when-to-use or when-not-to-use guidance relative to siblings (e.g., for exact ID use get_school_by_beis_id).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv1.0.3May 31, 2026
- First observeddataset_stats
- First observedget_school_by_beis_id
- First observedlist_divisions
- First observedlist_regions
- First observedsearch_schools

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: dataset stats, direct lookup by ID, listing divisions, listing regions, and flexible search. No overlaps.

Naming Consistency4/5

Tools use snake_case with a verb_noun pattern (get_school_by_beis_id, list_divisions, etc.), except dataset_stats which is noun_noun. Minor deviation but still readable and consistent in style.

Tool Count5/5

Five tools is well-scoped for a schools data query server. Each tool covers a core operation without unnecessary clutter.

Completeness4/5

The set covers key query needs: search, direct lookup, region/division lists, and stats. Minor gaps like filtering by municipality directly are covered by search.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

UNESCO UIS — Education, Science & Culture Statistics (provenance-first)A
io.github.SidneyBissoli
UNESCO UIS statistics (education, science, culture) with full provenance and fixed releases.
Research & Data Open Data
511
usaspending-mcp-server A
io.github.cyanheads
Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Government Data Open Data
1823
Nova Scotia Data Explorer A
ca.scotiasignal
Search, explore, and analyze hundreds of datasets from the Nova Scotia government's datasets
Government Data Open Data Search
42
hithereiamaliff-mcp-datagovmy BOAuth
ai.smithery
This MCP server provides seamless access to Malaysia's government open data, including datasets, w…
Government Data Open Data
23

Related MCP Servers

NEIS MCP Server
Education & Learning Tools Government Data Search
gandandev
F
license
Not graded
quality
D
maintenance
Enables access to Korean school information through the National Education Information System (NEIS) API. Provides tools to search schools, retrieve meal menus, class timetables, and school event schedules.
Updated 10 months ago (2025-11-02 03:03 UTC)
1
-
Skolverket MCP Server
Education & Learning Tools Government Data Open Data
isakskogstad
A
license
A
quality
D
maintenance
Enables LLMs to access Swedish educational data through Skolverket's open APIs, allowing users to search curricula, courses, schools, adult education programs, and analyze educational requirements and standards. Provides comprehensive tools for teachers, students, guidance counselors, and educational researchers to interact with official Swedish education data.
Updated 4 months ago (2026-04-22 09:20 UTC)
27
10
MIT
schooldigger-mcp
Education & Learning Tools Search
pajaydev
A
license
Not graded
quality
D
maintenance
Integrates with SchoolDigger's API to search schools, get rankings, and find districts by location. Enables querying school data through natural language.
Updated a year ago (2025-09-06 07:54 UTC)
1
MIT
uk-schools-mcp
Government Data Open Data Education & Learning Tools
mkb-123
A
license
A
quality
D
maintenance
MCP server providing access to comprehensive UK school data from official government sources, including search, details, near-postcode, comparisons, Ofsted ratings, and DfE education datasets.
Updated 7 months ago (2026-02-07 09:30 UTC)
11
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/darwinphi/ph-schools-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

PH Schools MCP Server

What This Server Provides

Install and Run

Which Setup to Use

Usage Scenarios

When to Use mcp.json

When to Use npx

When to Use npm install and npm start

CLI (published package)

Quick Verify

Dataset Configuration

VS Code MCP Config (Copy/Paste)

Claude Desktop Config (Copy/Paste)

Test Commands

Example Prompts

Publishing and Release Flow

License and Data Provenance

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

When to Use `mcp.json`

When to Use `npx`

When to Use `npm install` and `npm start`