Maldives Statistics MCP

A read-only, standard-stdio Model Context Protocol server for public information from the Maldives Bureau of Statistics. The site is a WordPress installation; this server uses its public WordPress pages and REST endpoints, plus public PDF attachments, without authentication.

The server is written in TypeScript and runs on Node.js using the official @modelcontextprotocol/sdk. It is model- and harness-agnostic: the same built process can be registered with any MCP host that supports local stdio servers.

Features

• Public reachability/status check for the Bureau of Statistics website.
• Search across WordPress posts and pages.
• Paginated page and post listings.
• Readable page content with links to public PDFs.
• Publication, press-release, statistics-section, jobs, and event discovery.
• Bounded inspection of same-host attachments, with optional built-in PDF text extraction (first 20,000 characters).
• Exact-host allowlisting for statisticsmaldives.gov.mv.
• Structured, machine-readable errors and JSON-serializable tool results.
• No credentials, cookies, authentication headers, or write operations.

Tool reference

The server exposes exactly the following 18 tools. Parameter defaults are part of the public contract in SPEC.md.

Tool	Description	Key parameters
mbs_status	Check site reachability and return HTTP status, page title, and UTC check time.	None
mbs_search	Search the WordPress search endpoint across posts and pages.	query: string, per_page: number = 10
mbs_list_pages	List report and other WordPress pages, optionally filtered and paginated.	search: string = "", per_page: number = 20, page: number = 1
mbs_list_posts	List news/release WordPress posts, optionally filtered and paginated.	search: string = "", per_page: number = 20, page: number = 1
mbs_get_page	Fetch one page by WordPress slug or an allowlisted full URL; return readable text and PDF links.	slug_or_url: string
mbs_publications	Parse the public publications index and return report-page links.	None
mbs_press_releases	Parse the public press-release page and return release links and direct PDF file URLs when available.	limit: number = 20
mbs_sections	Return the curated list of public statistics sections and their full URLs.	None
mbs_yearbook_editions	List Statistical Yearbook editions (2005–present) with URLs.	None
mbs_yearbook_tables	List a yearbook edition's tables (chapter + label + PDF/XLS links), optionally filtered by keyword.	year: number, query: string = ""
mbs_census_releases	List census release pages (e.g. Census 2022 statistical releases).	limit: number = 20
mbs_economic_survey	List Economic Survey report pages and PDFs.	None
mbs_downloads	List public downloads (forms and documents).	limit: number = 20
mbs_updates	List dated update posts (latest statistical releases).	limit: number = 10, page: number = 1
mbs_jobs	Parse the jobs page for main-content job links.	limit: number = 20
mbs_events	List events from the public WordPress event endpoint, including available ACF fields.	per_page: number = 10
mbs_attachment	Inspect an allowlisted public file with bounded HEAD/GET behavior; optionally extract the first 20,000 characters of a PDF.	url: string, extract_text: boolean = false
mbs_xlsx_table	Download and parse an allowlisted .xlsx (e.g. yearbook table) into rows of cell values.	url: string, max_rows: number = 200

Errors use the structured shape {"error": "<machine-readable reason>", "detail": "<human message>"}. The documented reasons include unreachable, http_error, no_results, invalid_url, blocked_url, parse_failed, and too_large.

Quickstart

Requirements: Node.js 20+ and npm.

From the repository root:

npm install
npm run build
npm start        # runs node dist/server.js

dist/server.js speaks MCP over stdio. Keep stdout available for protocol traffic; diagnostics go to stderr. PDF text extraction in mbs_attachment uses a small built-in extractor (uncompressed or zlib-inflated text streams); PDFs without extractable text return "text": null rather than failing the tool.

The examples below use this placeholder:

• <REPO_ROOT> — the absolute path to this checkout, such as /path/to/maldives-statistics-mcp.

Replace the placeholder before using a configuration. Do not put credentials in any MCP configuration for this server.

Registering with MCP hosts

All examples launch the same local stdio process: node <REPO_ROOT>/dist/server.js (use an absolute path to the node binary if it is not on the host's PATH). Client configuration schemas and command names can change between releases; consult the host's current documentation if your installed version differs.

Claude Desktop — claude_desktop_config.json

Add the server under mcpServers in Claude Desktop's configuration file:

{
  "mcpServers": {
    "maldives-statistics": {
      "command": "node",
      "args": ["<REPO_ROOT>/dist/server.js"]
    }
  }
}

Restart or reload Claude Desktop after saving the file.

Claude Code

Register the command from a shell:

claude mcp add maldives-statistics -- node <REPO_ROOT>/dist/server.js

Use the host's MCP listing command to confirm that maldives-statistics is registered.

Codex CLI

A local stdio server can be added with the Codex CLI command form:

codex mcp add maldives-statistics -- node <REPO_ROOT>/dist/server.js

The equivalent project/user configuration, where supported, is conceptually:

[mcp_servers.maldives-statistics]
command = "node"
args = ["<REPO_ROOT>/dist/server.js"]

Cursor

In Cursor's MCP settings or .cursor/mcp.json, add:

{
  "mcpServers": {
    "maldives-statistics": {
      "command": "node",
      "args": ["<REPO_ROOT>/dist/server.js"]
    }
  }
}

Gemini CLI

In the applicable Gemini CLI settings.json (commonly ~/.gemini/settings.json), add the server under mcpServers:

{
  "mcpServers": {
    "maldives-statistics": {
      "command": "node",
      "args": ["<REPO_ROOT>/dist/server.js"]
    }
  }
}

Merge this object into an existing settings file rather than replacing unrelated settings.

Windsurf

In Windsurf's MCP configuration (commonly ~/.codeium/windsurf/mcp_config.json), use the standard mcpServers shape:

{
  "mcpServers": {
    "maldives-statistics": {
      "command": "node",
      "args": ["<REPO_ROOT>/dist/server.js"]
    }
  }
}

Cline / Roo Code

In the relevant MCP settings JSON for Cline or Roo Code, add this entry to mcpServers:

{
  "mcpServers": {
    "maldives-statistics": {
      "command": "node",
      "args": ["<REPO_ROOT>/dist/server.js"],
      "disabled": false
    }
  }
}

The exact settings-file location is controlled by the extension and editor profile; the server entry itself is a local stdio command.

VS Code

Create or edit .vscode/mcp.json (or the user MCP configuration) with VS Code's servers schema:

{
  "servers": {
    "maldives-statistics": {
      "type": "stdio",
      "command": "node",
      "args": ["<REPO_ROOT>/dist/server.js"]
    }
  }
}

Hermes Agent

Hermes Agent is one option among many MCP hosts. Register the same stdio command with:

hermes mcp add maldives-statistics --command /usr/bin/node --args <REPO_ROOT>/dist/server.js

After registration, use the host's MCP test/list facility and start a new session if the host injects tools only at session start.

Generic stdio clients

For a client that accepts a command and argument array, use:

{
  "name": "maldives-statistics",
  "transport": "stdio",
  "command": "node",
  "args": ["<REPO_ROOT>/dist/server.js"]
}

The equivalent shell command is:

node <REPO_ROOT>/dist/server.js

The client must own the process's stdin/stdout and speak the MCP stdio protocol. Do not pipe ordinary logs into stdout.

Testing

Run the protocol tests from the repository root (build first):

npm run build
npm test

The default suite includes live checks against the public website. To skip live network checks while still exercising initialization, tool discovery, and the blocked-URL safety path:

MBS_OFFLINE=1 npm test

A successful live run verifies MCP initialization, discovery of all 18 tools, status, search, publications, a page lookup, attachment handling, yearbook tables, XLSX parsing, census releases, economic survey, downloads, and updates. Network availability and the remote site's current content can affect live checks.

Limitations

• Read-only: this server only reads public content. It does not authenticate, submit forms, upload files, create or modify records, or write to the website.
• The .Stat data portal is unavailable: https://data.statisticsmaldives.gov.mv/ currently has a broken TLS certificate and is intentionally not used.
• Source format: data is obtained from public WordPress pages, WordPress REST responses, and PDF attachments on the Bureau's site; it is not a replacement for the Bureau's official source documents.
• Jobs may be sparse: the jobs page may contain few or no extractable job links at a given time. In that case mbs_jobs returns an empty list and a note when available.
• Remote dependency: live results depend on the public site's reachability, HTTP behavior, page structure, and current content.
• Bounded extraction: attachment downloads and extracted PDF text are intentionally size-limited. PDF text extraction is minimal (uncompressed/inflated text streams only); scanned or exotic PDFs return "text": null.
• Exact host allowlist: only statisticsmaldives.gov.mv is accepted for fetches, including attachment inspection. Off-host links are not followed.

License

This project is released under the MIT License. Copyright 2026 Maldives Statistics MCP contributors.