pse-edge-mcp

An MCP server exposing Philippine Stock Exchange data from the PSE Edge portal — quotes, price history, disclosures, financial reports, and market data — to Claude and any other MCP client.

Unofficial. PSE Edge has no public API; this project speaks to the same endpoints the portal's own pages use. It is not affiliated with or endorsed by the PSE. Data is provided as-is for personal/research use, with no warranty.

Contents

• Features
• Quick start
• Design: end-of-day prices, fetch-once everything else
• Tools, resources, prompts
• Architecture
• Golden path: one request traced
• Connecting to a hosted server
• Run with Docker Compose
• Configuration
• Container image
• Production
• Development
• Contributing
• License

Features

• 13 read tools + 1 action tool covering quotes, price history, disclosures (metadata, full-text, and detail), company profiles, financials, dividends, indices, and market summary — plus an attachment resource, two prompts with symbol completion, and tool annotations.
• Deliberately gentle on PSE Edge: every unique query hits it at most once per day, and prices follow a strict market-boundary freeze.
• OAuth 2.1 + passkeys for humans (no passwords anywhere), client_credentials for headless agents — both opt-in; stdio needs nothing.
• Postgres optional: zero-config in-memory for local stdio, or a shared cache + an ever-deepening EOD archive when DATABASE_URL is set.
• Loud on drift: a nightly canary validates live pages against the real models and alerts only on failure; a restyled page raises an error, never partial data.
• Multi-arch container image (amd64 + arm64), gated on necessity — the image contains exactly the runtime dependency closure and nothing else.

Quick start

Claude Desktop / Claude Code (stdio):

uvx pse-edge-mcp

{
  "mcpServers": {
    "pse-edge": { "command": "uvx", "args": ["pse-edge-mcp"] }
  }
}

A hosted deployment (auth on) is a normal OAuth 2.1 protected resource — modern clients need only the URL and drive the whole flow themselves (details below):

{
  "mcpServers": {
    "pse-edge": { "url": "https://your-host.example.com/mcp" }
  }
}

Docker (HTTP + Postgres):

cp .env.example .env   # set POSTGRES_PASSWORD
docker compose up --build

Design: end-of-day prices, fetch-once everything else

Four layers, one direction of dependency. Every read goes through FreezeService.get() with an explicit per-domain policy — no tool ever touches the HTTP client directly. ★ marks the invariant the whole design exists to protect, and it guards prices only.

flowchart TD
    C["MCP client"] -- "tool call" --> S["<b>server.py</b> · MCP boundary<br/>validate args · delegate · shape reply"]
    S --> R["<b>repositories.py</b> · one per domain<br/>cache key · freeze read · parse · endpoint routing"]
    R --> F["<b>service.py</b> · FreezeService ★<br/>3 policies · miss → fetch once"]
    F --> P["<b>client.py</b> · PseEdgeClient<br/>throttled HTTPS · single-flight · 2 dialects"]
    P --> E["PSE Edge<br/>edge.pse.com.ph"]

★ Market-boundary freeze — prices only. A cached stock price is never refetched while the market is open (09:30–15:00 Asia/Manila, trading days) — the last close answers, flagged stale. A price nobody has ever asked for is the one exception: fetched once mid-session and served as identity + previous_close only (every session-moving field withheld), with stale: true plus a meta.note saying it is not a realtime value; the settled figures replace it after the close.

If PSE Edge is unreachable and an expired entry exists, tools serve it flagged meta.stale: true rather than discarding real data for an error. EDGE_UNAVAILABLE means unreachable and nothing cached.

Every data tool returns the same envelope — meta is the freshness contract:

{
  "data": { /* …StockQuote… */ },
  "meta": {
    "as_of":       "2026-08-06T15:00:00+08:00",  // ISO-8601, Asia/Manila
    "valid_until": "2026-08-07T15:00:00+08:00",  // null when immutable
    "from_cache":  false,
    "stale":       false,                        // true = not a settled EOD value
    "data_policy": "EOD-frozen",                 // "daily-refresh" / "immutable" elsewhere
    "note":        null                          // freshness caveat, e.g. "not a realtime value"
  }
}

Tools, resources, prompts

Beyond tools, the server exposes the attachment resource above, two prompts (market_recap, company_briefing(symbol) — the symbol argument autocompletes from PSE Edge's own lookup), and MCP tool annotations so hosts can auto-approve the read-only tools. It is described for the MCP Registry in server.json.

send_email is the only tool that acts rather than reads. It has no recipient argument: the message always goes to the account that authenticated the session, so it cannot be used as a relay and there is nothing for prompt injection to redirect — which matters because this server returns disclosure text the operator does not control. It appears only on deployments with auth enabled (there is no verified address otherwise), the body is escaped rather than rendered as HTML, and it is capped at 20 messages per user per day.

Disclosure tools return metadata and links only — this server never downloads or parses attachments (beyond the explicit resource read), so your MCP client can fetch the returned URLs itself if it needs the files. Note that Edge's own full-text index is partial (roughly 2023–2025 at last check), so search_disclosure_fulltext is not a substitute for search_disclosures; it reports this limit in its results.

Financial figures are returned exactly as PSE Edge prints them and are never rescaled — Edge's own units labels are inconsistent between its annual and quarterly sections, so each period reports its currency_units for you to check. Index changes are signed here even though Edge prints them unsigned (it shows direction only as a colour and an arrow).

Architecture

The layers