boe-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@boe-mcp what did the BOE publish today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 |
| What the BOE published on a day (today by default), by section, with links to the signed PDFs |
| Find a rule in the consolidated collection by title words, full-text words or official number |
| Whether a rule is in force today, its outline and the later rules that changed it |
| 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
readscope (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 stdioDevelop
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.zipTests 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
readscope. 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 toolsget_daily_summaryBOE of the dayARead-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 changesARead-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 articleARead-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 legislationARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Spain consolidated legislation — Agencia Estatal Boletín Oficial del Estado (BOE), open-data API.
Search Spain's BOE/BORME gazettes, open EU funding calls and EU TED tenders. Keyless sources.
Spain's Official State Gazette (BOE) items as tagged JSON: grants, tax, public jobs, full text.
AI legal copilot for foreigners in Spain: immigration and housing rental, cited to Spanish law.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables LLMs like Claude to query the official Spanish BOE API for consolidated legislation, daily summaries, and auxiliary government tables.3161MIT
- AlicenseAqualityDmaintenanceEnables querying Spanish BOE consolidated legislation, daily summaries, and legal reference data through natural language using the Model Context Protocol.56MIT
- AlicenseAqualityDmaintenanceEnables querying and analyzing Spanish (BOE) and EU (EUR-Lex) legal documents, with advanced search, PDF extraction, and cross-reference detection.838 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT