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.

Related MCP server: @nor-data/statfin-mcp

Tool reference

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

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.