Skip to main content
Glama

boe-mcp

A remote Model Context Protocol (MCP) server that lets AI agents read Spain's official gazette, the Boletín Oficial del Estado (BOE): what was published on a day, which rules are in force, what changed them and what an article says today.

It is written in Python with the official MCP SDK, protected with OAuth 2.1 (Amazon Cognito as authorization server, tokens bound to this server's URL), and deployed on AWS Lambda behind API Gateway with Terraform.

NOTE

The texts it returns come from the BOE's open-data API. Consolidated texts are informative: only the signed PDF of the BOE is official. This project is not affiliated with the BOE.

Tools

Tool

What it does

get_daily_summary

What the BOE published on a day (today by default), by section, with links to the signed PDFs

search_legislation

Find a rule in the consolidated collection by title words, full-text words or official number

get_legislation

Whether a rule is in force today, its outline and the later rules that changed it

read_legislation_block

The latest wording of one article or other block, whether it is in force today, any wording approved for later, and its history

All four are read-only. A typical question, «¿Ha cambiado el artículo 23 de la ley de protección de datos?», makes the model search for 3/2018, read the outline of BOE-A-2018-16673, and read block a2-5, which Ley 10/2025 rewrote with effect from 28 December 2025.

Related MCP server: boe-mcp

How it works

flowchart LR
    C["Claude Code / Claude.ai"] -->|"MCP over HTTPS, Bearer token"| G["API Gateway HTTP API<br/>throttled"]
    C -.->|"OAuth 2.1 + PKCE"| A["Amazon Cognito"]
    G --> L["AWS Lambda<br/>Python 3.14, arm64"]
    L -.->|"JWKS"| A
    L -->|HTTPS| B[("BOE open-data API")]
  • Transport: Streamable HTTP, stateless, one JSON answer per request (ADR 0001). It speaks MCP 2026-07-28 and the older handshake revisions.

  • Authorization: the server is an OAuth 2.1 resource server. It publishes Protected Resource Metadata (RFC 9728) and accepts only Cognito access tokens whose audience is its own URL (RFC 8707), from a known client, with the read scope (ADR 0002).

  • Hosting: API Gateway in front of Lambda, with the Lambda Web Adapter running the unchanged ASGI app (ADR 0003); infrastructure in Terraform (ADR 0004).

A step-by-step explanation in Spanish, from what MCP is to how the token is checked, is in docs/guia.md.

Use it

Hosted, with Claude: see docs/deploy.md. Users are created by an administrator; there is no public sign-up.

Locally, over stdio, no login needed:

uv tool install git+https://github.com/sergiooriola/boe-mcp
claude mcp add boe -- boe-mcp stdio

Develop

Requires uv and, for the infrastructure, Terraform 1.11 or later.

uv sync
make check   # Ruff format and lint, strict mypy, pytest with 90 % minimum coverage
make build   # Lambda package for arm64 in build/lambda.zip

Tests run against responses recorded from the live BOE API and never touch the network. The OAuth tests sign their own tokens with a throwaway RSA key. A few tests ask the live API about facts that do not change, to notice when it changes under the recordings. They are skipped by default, run with uv run pytest -m live --no-cov, and a workflow runs them every Monday.

Security

  • Only RS256 tokens signed by the user pool, issued for this server's URL, to a registered app client, with the read scope. Users sign in with a password and an authenticator app.

  • Model-written arguments are untrusted: identifiers are validated before they reach a URL, search input cannot add operators to the BOE's query language, and XML is parsed with defusedxml.

  • Requests to any other host name are refused (DNS rebinding protection); API Gateway caps traffic at 5 requests per second.

  • The function's only AWS permission is to write its own logs. The logs never contain tool arguments or answers. Access lines keep the caller's IP address, and everything is deleted after 30 days.

Report vulnerabilities through GitHub's private reporting.

Cost

At a few hundred requests a month, under 0.05 USD a month in eu-south-2: Lambda and Cognito stay within their always-free allowances, and API Gateway costs 1.11 USD per million requests. A 2 USD monthly budget emails at half of it.

Data

"Basado en datos de la Agencia Estatal Boletín Oficial del Estado" (reuse conditions).

License

MIT.

Available Tools

4 tools
get_daily_summaryBOE of the dayA
Read-only

List what the BOE published on one day, with links to the official PDFs.

The answer always counts the items in every section, so a filtered or paged answer still shows what else that day holds. Sundays have no bulletin.

Inputs: date, limit, offset, sections, +1 more. Returns: What the BOE published on one day.

get_legislationRule status, outline and changesA
Read-only

Describe one consolidated rule: its status today, its outline and its later changes.

Later changes come most recent first. Use the outline's block_id with read_legislation_block to read an article.

Inputs: law_id (required). Returns: A consolidated rule: what it is, whether it is in force, its outline and its ch…

read_legislation_blockRead an articleA
Read-only

Read the latest wording of one block of a consolidated rule, and whether it is in force.

A block is an article, the preamble, an annex or a provision. The answer also gives any approved wording that takes effect later, and lists the earlier versions of the block with the rules that introduced them. Check in_force before presenting the text as law.

Inputs: law_id (required), block_id (required). Returns: The latest wording of one block of a consolidated rule, and whether it is in fo…

search_legislationSearch legislationA
Read-only

Search Spain's consolidated legislation: laws, royal decrees, orders and more.

Give at least one of title_words, text_words or official_number. Results come newest publication first. The collection holds the most relevant state and regional rules, not every item ever published in the BOE.

Inputs: limit, scope, offset, text_words, +5 more. Returns: A page of search results, newest publication first.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: daily bulletin listing, legislation search, rule-level overview, and block-level reading. The workflow from search to rule description to block text is easy to follow, with no apparent overlap.

    Naming Consistency5/5

    All names use consistent snake_case and follow a verb_noun pattern: get_daily_summary, search_legislation, get_legislation, read_legislation_block. The verbs vary appropriately by action without introducing confusion.

    Tool Count5/5

    Four tools are well-scoped for a BOE-focused server covering daily summaries and consolidated legislation. Each tool serves a distinct stage of access or retrieval, and none feels redundant.

    Completeness4/5

    The surface covers the core legislative workflow: search rules, inspect a rule's structure and changes, and read specific blocks. Minor gaps remain, such as no keyword search over daily summaries and no direct document-content retrieval beyond linked PDFs, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search Spain's consolidated legislation by title, inspect any statute's metadata and article table of contents, and read every historical version of a chosen article. Also retrieves the daily table of contents of the Spanish state gazette, grouped by section and issuing department, via the Agencia Estatal Boletín Oficial del Estado open-data API.
      90 npm
      MIT