@cyanheads/eur-lex-mcp-server

Public Hosted Server: https://eur-lex.caseyjhand.com/mcp

Overview

EU legislation, CJEU case law, and treaties over the EU Publications Office's CELLAR semantic repository and the EUR-Lex content API. Search documents and case law, fetch full text, resolve citations, traverse the amendment and citation graph, and browse the EuroVoc thesaurus from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

All resource data is also reachable via tools.

Prompts

Related MCP server: eurlex-mcp-server

Capability reference

eurlex_search_documents tool

• Keyword matches English titles via the full-text index, or CELEX substrings — no full-text body search; at least one filter is required

• document_type (REG, DIR, DEC, TREATY, JUDG, OPIN_AG, PROP, REC) expands to its full CELLAR authority family; include_consolidated folds in consolidated texts of that category

• Date range (date_from/date_to), EuroVoc concept URI (from eurlex_browse_subjects), author institution, and in-force-only filters

• Pagination via offset and limit (max 100); each result flags is_consolidated

• Typed errors: no_filters, invalid_date_range, no_results

eurlex_get_document tool

• Accepts exactly one of celex_number, eli_uri, or work_uri

• Body as html (default), markdown (server-side converted), or xml (Formex4); all 24 EUR-Lex language codes, case-insensitive, defaulting to and falling back to English

• content_mode "paged" (default, offset/limit window), "full" (first window from zero), or "metadata_only"; paged and full windows both cap at 100,000 characters, with content_chars_total/has_more to page the rest

• outline: true returns chapter/article/annex/recital headings with offsets; select (e.g. { articles: "1,5,17" }) returns just those sections

• resolve: "current_consolidated" serves the newest consolidated version instead of the requested base act; is_superseded/current_consolidated_celex/consolidated_as_of flag a stale base act either way

• Typed content_challenge error when EUR-Lex returns a WAF bot-challenge instead of text

eurlex_lookup_celex tool

• Accepts a CELEX number or ELI URI; identifier_type auto-detects the format or can be set explicitly

• Returns work URI, confirmed CELEX number, resource type, and date — found: false for a well-formed identifier that matches no work

• ambiguous_identifier error when auto-detection can't classify the input

eurlex_get_cases tool

• Filters: case_number (C-131/12 / T-131/12), court (CJEU or GC), case_type (judgment, order, ag_opinion), keyword, and date range

• Primary records only by default — judicial information notices, abstracts, summaries, and corrigenda excluded; include_derivative includes them

• Party names, subject matter, and case reference are parsed from the raw CELLAR title into display_title, parties, subject_matter, case_reference

• Pagination via offset and limit (max 100)

eurlex_get_relations tool

• Accepts exactly one of celex_number or work_uri

• relation_types filters to a subset of cites, amends, amended_by, repeals, repealed_by, implicitly_repeals, implicitly_repealed_by, legal_basis, consolidated_version, national_transposition; omit for all

• One-hop only, paginated per relation type and direction via offset/limit (max 100, default 100)

• Each relation carries relation_type, direction (outgoing/incoming), related_work_uri, and related_celex_number when known

• empty_relation_types distinguishes "no edges of this type" from "edges paged out of this window"; no_relations fires only when the first page is empty

eurlex_browse_subjects tool

• Matches both preferred and alternative (non-preferred) EuroVoc labels, so a common synonym resolves to the concept it stands for

• Returns concept URI, preferred label, code, broader (parent) label, and the alternative label that matched when one did

• Supports all EU official languages via language; defaults to English

• Pagination via offset and limit (max 50)

eurlex_query_sparql tool

• Read-only SELECT only — update forms and ASK/CONSTRUCT/DESCRIBE are rejected before execution

• cdm:, skos:, and xsd: prefixes are auto-injected; results capped at 100 rows

• Optional timeout_hint (1000–55000 ms); the Virtuoso endpoint enforces a 60-second hard limit

• Typed errors: not_read_only, sparql_error, sparql_timeout

eurlex://document/{celexNumber} resource

• Metadata snapshot as application/json — resource type, author institution(s), date, title, in-force flag, legal basis, EuroVoc subjects

• celexNumber comes from eurlex_search_documents, eurlex_get_cases, or eurlex_lookup_celex

eurlex://document/{celexNumber}/relations resource

• One-hop relationship summary — amendment chain, consolidations, national transposition, legal basis, citations — capped at 25 per relation type

• truncated plus a continuation pointer to eurlex_get_relations when more relations exist

eurlex_comparative_analysis prompt

• Arguments: domain required; focus optional, folded into its matching analysis axis or added as its own section

• Returns a research plan chaining eurlex_browse_subjects → eurlex_search_documents → eurlex_get_document → eurlex_get_relations for the EU side and courtlistener_search_opinions for the US side, plus a six-axis analysis framework

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.

EUR-Lex-specific:

• No API key required — CELLAR SPARQL and the EUR-Lex REST content endpoints are both publicly accessible

• SPARQL is POSTed with CDM prefix declarations built in; server-side LIMIT enforcement (max 100) guards against Virtuoso timeouts

• Act text is fetched via CELLAR content negotiation (/resource/celex/{CELEX}); HTML and Formex4 XML pass through, Markdown is converted server-side

• Virtuoso errors (HTTP 200 with a Virtuoso 37000 Error body) are classified and re-raised as ServiceUnavailable or InvalidParams

• Automatic English fallback when a requested translation is unavailable, with requested/effective language reported

Agent-friendly output:

• EuroVoc prerequisite guidance in server-level instructions — agents are directed to eurlex_browse_subjects before concept-filtered searches

• eurlex_lookup_celex confirms CELEX/ELI existence upfront, preventing downstream errors in document or relation fetches

• content_status, content_unavailability_reason, and requested/effective language fields distinguish skipped, available, absent, upstream-failed, and incomplete content without string parsing

• Typed reason codes on every tool's error contract let agents branch on outcomes programmatically

Getting started

Public Hosted Instance

A public instance is available at https://eur-lex.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "eur-lex-mcp-server": {
      "type": "streamable-http",
      "url": "https://eur-lex.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. No API key is required.

{
  "mcpServers": {
    "eur-lex-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/eur-lex-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "eur-lex-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/eur-lex-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

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

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

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

• No API key needed — EUR-Lex and CELLAR are publicly accessible.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd eur-lex-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# All server-specific vars have sensible defaults — no required vars

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

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 eur-lex-mcp-server .
docker run --rm -p 3010:3010 eur-lex-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/eur-lex-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 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 and resources via the barrels in src/mcp-server/*/definitions/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.