Guardian Mcp Server

Overview

The Guardian's journalism archive (1999–present), via the Guardian Open Platform API. Search full text, browse by section or tag, and fetch individual articles from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

Tools

Capability reference

guardian_search_articles _tool

• Boolean query syntax (AND/OR/NOT, quoted phrases), optional section/tag/contributor and from_date/to_date (YYYY-MM-DD) filters; order_by: relevance (default), newest, or oldest; page + page_size (1–50, default 10)
• Articles carry metadata, HTML-stripped body text and a truncated flag; results include total, page, pages, page_size, and order_by
• Search-specific reasons: no_results, invalid_date. Dates must be real calendar dates, including leap-year rules; blank bounds are omitted before calling the API.
• tag accepts comma (AND), pipe | (OR), hyphen - (NOT), and parentheses. For example, environment/climate-crisis|environment/flooding. When adding contributor: "profile/georgemonbiot", group the expression as (environment/climate-crisis|environment/flooding); the two filters are comma-joined unchanged.

guardian_get_article _tool

• Required article_id: the path-slug id returned by guardian_search_articles or guardian_browse_content
• Returns HTML-stripped body text, metadata, contributors, pillar/section classification, and truncated
• Article-specific reason: not_found.

guardian_browse_content _tool

• Four mode values: section_latest (requires section_id), tag_latest (requires tag_id), list_sections, list_tags; page + page_size (1–50, default 10) for articles and tags
• list_tags filters by optional query and tag_type (keyword, contributor, blog, series, tone, type, publication, newspaper-book, newspaper-book-section); output carries mode, total, and the matching results/sections/tags array
• Browse-specific reasons: missing_section_id, missing_tag_id, section_not_found, tag_not_found. tag_id in tag_latest accepts the same boolean expressions as search's tag.

All three tools use authored Guardian error messages and canonical status/body diagnostic fields, without request URLs or duplicate aliases. HTTP failures preserve status-specific error codes. unauthorized (401), access_denied (403), request_rejected (400), validation_failed (422), invalid_request, request_conflict, and request_not_found are explicitly nonretryable and carry parameter or configuration recovery. Article/section 404 retain not_found/section_not_found. api_timeout (408/425/504), rate_limited (429), and api_error (other 5xx) are retryable after the existing three internal retries. api_unsupported (501) is nonretryable and is attempted once. Each reason's recovery hint and retryability appear on both client surfaces.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Guardian-specific:

• Wraps the Guardian Open Platform API with a free non-commercial developer key
• Full body text extraction — HTML stripped, not just headlines or abstracts
• Contributor ID discovery via guardian_browse_content mode list_tags with tag_type=contributor
• Section and tag taxonomy browsing (list_sections, list_tags) for filter discovery before searching
• Free tier: 5,000 requests/day, 12 calls/second — the server applies no additional throttling

Agent-friendly output:

• Search and article-returning browse modes cap previews at 2,000 words. Each article renders its explicit truncated state; when true, call guardian_get_article with its id as article_id for complete HTML-stripped text without a word cap.
• Typed error reasons across all three tools, each paired with a recovery hint
• total / page / pages on every paginated response so callers can track result scope
• Declared recovery hints on error responses, with a request ID for matching server logs

Getting started

Add the following to your MCP client configuration file. Register for a free Guardian Open Platform API key at open-platform.theguardian.com/access.

{
  "mcpServers": {
    "guardian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/guardian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GUARDIAN_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "guardian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/guardian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GUARDIAN_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "guardian-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "GUARDIAN_API_KEY=your-api-key",
        "ghcr.io/cyanheads/guardian-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 GUARDIAN_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A free Guardian Open Platform API key — register at open-platform.theguardian.com/access. The non-commercial developer tier is free and instant.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/guardian-mcp-server.git

2. Navigate into the directory:

cd guardian-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# Edit .env and set GUARDIAN_API_KEY

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t guardian-mcp-server .
docker run --rm -e GUARDIAN_API_KEY=your-api-key -p 3010:3010 guardian-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/guardian-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools in the createApp() tools array in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Powered by The Guardian.