@cyanheads/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

Related MCP server: Guardian News MCP Server

Capability reference

guardian_search 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

• Typed error reasons: unauthorized, no_results, invalid_date, api_error (retryable)

guardian_get_article tool

• Required article_id: the path-slug id returned by guardian_search or guardian_browse

• Returns HTML-stripped body text, metadata, contributors, pillar/section classification, and truncated

• Typed error reasons: unauthorized, not_found, api_error (retryable)

guardian_browse 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

• Typed error reasons: unauthorized, missing_section_id, missing_tag_id, section_not_found, tag_not_found, api_error (retryable)

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 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:

• Article bodies are capped at 2,000 words across all three tools; truncated: true signals a cut. Read the article's web_url for the full text.

• 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.