MCP-BOE

MCP server para o BOE 🇪🇸 — Acesso a legislação consolidada, sumários diários e tabelas oficiais do Boletim Oficial do Estado mediante Model Context Protocol e API REST.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP BOE 🇪🇸

Model Context Protocol para o Boletín Oficial del Estado espanhol

Um servidor MCP que permite ao Claude e outros LLMs acessar a API oficial do BOE para consultar legislação consolidada, resumos diários e tabelas auxiliares do governo espanhol.

🚀 Características

🔍 Busca de Legislação: Buscar em mais de 50.000 normas consolidadas com filtros por departamento, faixa normativa, matéria e datas
📰 Resumos do BOE/BORME: Acessar publicações diárias, buscas recentes e resumos semanais
🏛️ Tabelas Auxiliares: Consultar códigos de departamentos, matérias, faixas normativas e âmbitos
📄 Leitura de PDFs: Baixar e extrair o texto de qualquer documento do BOE para analisá-lo
💬 Prompts integrados: Modelos de consulta prontos para usar no Claude
📊 Dados Oficiais: Conecta diretamente com a API oficial do BOE
⚙️ Configurável: Timeout, tentativas e nível de log via variáveis de ambiente

🛠️ Instalação

Pré-requisitos

Python 3.10 ou superior (exigido pela biblioteca mcp)
uv (recomendado) ou pip

Opção 1: uvx — sem instalação (Recomendado)

Com uvx você não precisa clonar o repositório nem gerenciar dependências:

uvx --from git+https://github.com/ComputingVictor/MCP-BOE.git mcp-boe

Opção 2: A partir do código-fonte com uv

git clone https://github.com/ComputingVictor/MCP-BOE.git
cd MCP-BOE

# Instalar dependencias y ejecutar
uv run python -m mcp_boe.server

Opção 3: Instalação com pip

git clone https://github.com/ComputingVictor/MCP-BOE.git
cd MCP-BOE
pip install -e .

🖥️ Configuração com Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Com uv (Recomendado)

{
  "mcpServers": {
    "mcp-boe": {
      "command": "uv",
      "args": [
        "run",
        "--python", "3.12",
        "--project", "/ruta/absoluta/a/MCP-BOE",
        "python", "-m", "mcp_boe.server"
      ]
    }
  }
}

Substitua /ruta/absoluta/a/MCP-BOE pelo caminho real onde você clonou o repositório.

Com uvx

{
  "mcpServers": {
    "mcp-boe": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ComputingVictor/MCP-BOE.git", "mcp-boe"]
    }
  }
}

Reinicie o Claude Desktop após salvar as alterações.

⚡ Configuração com Claude Code

Com uvx

{
  "mcpServers": {
    "mcp-boe": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ComputingVictor/MCP-BOE.git", "mcp-boe"],
      "transport": "stdio"
    }
  }
}

Você também pode usar o arquivo incluído no repositório:

# Desde el directorio del proyecto
claude --mcp-config claude_mcp_config_uvx.json

💬 Prompts disponíveis

O servidor inclui 4 prompts integrados acessíveis pelo seletor de prompts do Claude:

`buscar_legislacion`

Busca e resume normas do BOE.

Argumento	Descrição	Obrigatório
`tema`	Texto ou nome da norma a buscar	✅
`departamento`	Ministério ou órgão emissor	❌

Exemplos:

tema: protección de datos → encontra RGPD e LOPDGDD
tema: Ley 40/2015 → Lei de Regime Jurídico do Setor Público
tema: tráfico, departamento: Ministerio del Interior

`analizar_norma`

Análise completa de uma norma: metadados, estado de vigência, estrutura e relações com outras normas.

Argumento	Descrição	Obrigatório
`id_norma`	Identificador BOE (ex: `BOE-A-2015-10566`)	✅

Exemplos:

BOE-A-1978-31229 → Constituição Espanhola
BOE-A-2015-10566 → Lei 40/2015 de Regime Jurídico do Setor Público
BOE-A-2018-16673 → Lei Orgânica de Proteção de Dados

`resumen_boe_dia`

Resumo das publicações mais relevantes do BOE de uma data específica.

Argumento	Descrição	Obrigatório
`fecha`	Data no formato AAAAMMDD	✅
`seccion`	Seção do BOE: `1`, `2A`, `2B`, `3`, `4`, `5`	❌

Exemplos:

data: 20250101 → publicações de 1º de janeiro de 2025
data: 20240529, seção: 1 → apenas disposições gerais

`comparar_normas`

Compara duas normas e identifica relações de modificação ou revogação entre elas.

Argumento	Descrição	Obrigatório
`id_norma_1`	Identificador da primeira norma	✅
`id_norma_2`	Identificador da segunda norma	✅

Exemplo:

BOE-A-2015-10566 e BOE-A-2015-10565 → Lei 40/2015 e Lei 39/2015 (as duas grandes leis administrativas)

🔧 Ferramentas disponíveis

31 ferramentas no total organizadas em 5 grupos.

📜 Legislação Consolidada (9 ferramentas)

Ferramenta	Descrição	Parâmetros-chave
`search_consolidated_legislation`	Busca em mais de 50.000 normas consolidadas	`query`, `title`, `department_code`, `legal_range_code`, `matter_code`, `from_date`, `to_date`, `limit`, `include_derogated`
`get_consolidated_law`	Obtém metadados, análise jurídica e texto de uma norma	`law_id`, `include_metadata`, `include_analysis`, `include_full_text`, `include_eli_metadata`
`get_law_structure`	Índice completo de uma norma (artigos, disposições, anexos)	`law_id`
`get_law_text_block`	Texto de um artigo ou disposição específica	`law_id`, `block_id`
`find_related_laws`	Normas que modificam, revogam ou são modificadas por uma norma	`law_id`, `relation_type`
`compare_law_versions`	Compara o texto de uma norma entre duas datas, detectando artigos adicionados, modificados ou removidos	`law_id`, `from_date`, `to_date`, `granularity`
`search_law_articles`	Busca artigos específicos dentro de uma norma sem baixar o texto completo	`law_id`, `query`, `search_in`, `limit`
`get_law_metadata`	Obtém apenas os metadados de uma norma (faixa, data, órgão, estado, links) sem carregar o texto	`law_id`
`list_related_laws`	Lista normas relacionadas com controle granular sobre quais tipos de relação incluir	`law_id`, `include_derogating`, `include_development`, `include_references`

📰 Resumos BOE/BORME (7 ferramentas)

Ferramenta	Descrição	Parâmetros-chave
`get_boe_summary`	Resumo completo do BOE para uma data	`date`, `section_filter`, `department_filter`, `max_items`
`get_borme_summary`	Resumo do BORME (Registro Mercantil)	`date`, `province_filter`, `max_items`
`search_recent_boe`	Busca documentos nos últimos N dias	`days_back`, `search_terms`, `section_filter`
`get_weekly_summary`	Estatísticas e resumo de uma semana completa	`start_date`, `include_statistics`
`get_boe_summary_range`	Agrega os resumos de um intervalo de datas (máx. 31 dias) com filtro de seção	`from_date`, `to_date`, `section`, `max_items`
`watch_boe_changes`	Radar normativo: busca publicações recentes por palavras-chave	`days_back`, `keywords`, `sections`, `max_items`
`group_summary_by_department`	Agrupa as publicações de um intervalo de datas por departamento emissor	`from_date`, `to_date`, `sections`, `max_items_per_dept`

🏛️ Tabelas Auxiliares (10 ferramentas)

Ferramenta	Descrição
`get_departments_table`	Lista de departamentos oficiais com seus códigos
`get_legal_ranges_table`	Faixas normativas (Lei, Real Decreto, Ordem, etc.)
`get_matters_table`	Vocabulário controlado de matérias temáticas
`get_scopes_table`	Âmbitos normativos (estadual, autonômico)
`get_consolidation_states_table`	Estados de consolidação
`search_auxiliary_data`	Busca em todas as tabelas ao mesmo tempo
`get_code_description`	Descrição de um código específico
`search_departments_advanced`	Busca avançada de departamentos com filtro por código-pai (hierarquia)
`list_topics_for_law`	Lista as matérias do vocabulário controlado de uma norma específica
`suggest_auxiliary_filters`	Dado um texto livre, sugere códigos de departamento, faixa e matéria para filtrar buscas

🛠️ Qualidade de vida para LLMs (4 ferramentas)

Ferramenta	Descrição	Parâmetros-chave
`summarize_law_sections`	Resumo estruturado de uma norma com o primeiro parágrafo de cada artigo	`law_id`
`paginate_law_text`	Retorna o texto de uma norma por páginas usando um cursor opaco	`law_id`, `cursor`, `max_chars`
`explain_law_structure`	Descreve a estrutura hierárquica de uma norma com contagem de elementos por nível	`law_id`
`normalize_boe_reference`	Normaliza uma referência textual a uma norma ou resumo em campos estruturados	`reference_text`

📄 Leitura de PDFs (1 ferramenta)

Ferramenta	Descrição	Parâmetros-chave
`read_boe_pdf`	Baixa e extrai o texto de um PDF do BOE	`source`, `max_pages`

source aceita dois formatos:

URL direta: a que aparece no campo url_pdf dos resumos
https://www.boe.es/boe/dias/2025/03/28/pdfs/BOE-A-2025-6192.pdf
Identificador BOE: o servidor consulta a API para obter a data e constrói a URL
BOE-A-2025-6192 ou BOE-A-2015-10566

max_pages — páginas máximas a ler (por padrão 30, máximo 100).

Limites aplicados: PDFs de até 10 MB e 80.000 caracteres de texto retornado ao LLM.

Exemplos de uso no Claude:

Lee el PDF de BOE-A-2015-10566 y explícame qué regula la Ley 40/2015

Descarga https://www.boe.es/boe/dias/2025/03/28/pdfs/BOE-A-2025-6192.pdf y resume su contenido

Busca el sumario del BOE de hoy y léeme el PDF del primer real decreto que aparezca

📌 Formatos e valores úteis

Seções do BOE:

Código	Descrição
`1`	Disposições gerais
`2A`	Autoridades e pessoal — Nomeações
`2B`	Autoridades e pessoal — Concursos
`3`	Outras disposições
`4`	Administração da Justiça
`5`	Anúncios

Departamentos frequentes:

Código	Departamento
`7723`	Chefia do Estado
`1430`	Ministério da Justiça
`1470`	Ministério do Interior

Faixas normativas frequentes:

Código	Faixa
`1300`	Lei
`1250`	Lei Orgânica
`1200`	Real Decreto
`1100`	Real Decreto-lei
`800`	Ordem ministerial

⚙️ Variáveis de ambiente

Variável	Descrição	Valor padrão
`BOE_HTTP_TIMEOUT`	Timeout em segundos para requisições HTTP	`30.0`
`BOE_MAX_RETRIES`	Número máximo de tentativas diante de erros de rede ou 5xx	`3`
`BOE_RETRY_DELAY`	Segundos de espera base entre tentativas (backoff linear)	`1.0`
`LOG_LEVEL`	Nível de logging (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`

Exemplo de configuração no Claude Desktop:

{
  "mcpServers": {
    "mcp-boe": {
      "command": "uv",
      "args": ["run", "--project", "/ruta/a/MCP-BOE", "python", "-m", "mcp_boe.server"],
      "env": {
        "BOE_HTTP_TIMEOUT": "60",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

💡 Exemplos de uso

Buscar legislação a partir do Python

import asyncio
from mcp_boe.utils.http_client import BOEHTTPClient
from mcp_boe.tools.legislation import LegislationTools

async def main():
    async with BOEHTTPClient() as client:
        tools = LegislationTools(client)
        resultados = await tools.search_consolidated_legislation({
            "query": "Ley 40/2015",
            "limit": 3
        })
        for r in resultados:
            print(r.text)

asyncio.run(main())

Obter resumo do BOE

import asyncio
from datetime import datetime, timedelta
from mcp_boe.utils.http_client import BOEHTTPClient
from mcp_boe.tools.summaries import SummaryTools

async def main():
    async with BOEHTTPClient() as client:
        tools = SummaryTools(client)
        fecha = (datetime.now() - timedelta(days=2)).strftime("%Y%m%d")
        resultados = await tools.get_boe_summary({
            "date": fecha,
            "section_filter": "1",
            "max_items": 10
        })
        for r in resultados:
            print(r.text)

asyncio.run(main())

Diagnóstico de conectividade

# Verificar que la API del BOE es accesible
python -m mcp_boe.server --mode diagnose

🐛 Solução de problemas

O servidor não aparece no Claude Desktop

Verifique se o Python 3.10+ está disponível: python3 --version
Confira o caminho no config: deve ser absoluto, não relativo
Reinicie completamente o Claude Desktop (não apenas a janela)
Revise os logs no Claude Desktop → Ajuda → Abrir pasta de logs

Erro: `requires-python` / incompatibilidade de versão

A biblioteca mcp requer Python 3.10 ou superior. Force a versão com uv:

"args": ["run", "--python", "3.12", "--project", "/ruta/MCP-BOE", "python", "-m", "mcp_boe.server"]

Erro: `No module named 'mcp_boe'`

Certifique-se de passar --project para o diretório raiz do repositório (onde está pyproject.toml), não para o diretório src/.

A API do BOE não responde

python -m mcp_boe.server --mode diagnose

A API do BOE não publica horários de manutenção. Erros 5xx são tentados novamente automaticamente até 3 vezes.

📊 Estrutura do projeto

MCP-BOE/
├── src/mcp_boe/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py               # Servidor MCP: tools, prompts, resources
│   ├── models/
│   │   └── boe_models.py       # Modelos Pydantic y validadores
│   ├── tools/
│   │   ├── legislation.py      # 9 herramientas de legislación consolidada
│   │   ├── summaries.py        # 7 herramientas de sumarios BOE/BORME
│   │   ├── auxiliary.py        # 10 herramientas de tablas auxiliares
│   │   ├── analysis.py         # 4 herramientas de calidad de vida para LLMs
│   │   └── documents.py        # 1 herramienta de lectura de PDFs
│   └── utils/
│       └── http_client.py      # Cliente HTTP asíncrono con reintentos
├── examples/
│   └── basic_usage.py
├── tests/
├── pyproject.toml
├── claude_mcp_config.json      # Config de ejemplo para instalación local
├── claude_mcp_config_uvx.json  # Config de ejemplo con uvx
└── rest_api_wrapper.py         # API REST opcional (FastAPI)

🤝 Contribuindo

Fork do projeto
Crie uma branch (git checkout -b feature/nueva-funcionalidad)
Faça commit das alterações (git commit -m 'Agregar nueva funcionalidad')
Push para a branch (git push origin feature/nueva-funcionalidad)
Abra um Pull Request

Desenvolvimento local

git clone https://github.com/ComputingVictor/MCP-BOE.git
cd MCP-BOE
uv sync --extra dev
uv run python -m pytest tests/
uv run black src/

📝 Changelog

v0.1.0

Implementação inicial do servidor MCP
31 ferramentas: 9 de legislação, 7 de resumos, 10 de tabelas auxiliares, 4 de qualidade de vida para LLMs, 1 de leitura de PDFs
Ferramenta read_boe_pdf: baixa e extrai texto de PDFs do BOE por URL ou por ID de norma
4 prompts integrados: buscar_legislacion, analizar_norma, resumen_boe_dia, comparar_normas
2 recursos MCP: boe://help e boe://status
Cliente HTTP assíncrono com novas tentativas em erros de rede e 5xx
Configurável via variáveis de ambiente
Suporte para Python 3.10+

🔒 Segurança

A API do BOE é pública e não requer autenticação
Nenhum dado é armazenado localmente
O servidor respeita automaticamente os limites da API por meio de novas tentativas com backoff

📚 Referências

📄 Licença

MIT — veja LICENSE para mais detalhes.

👤 Autor

Víctor Viloria

Email: vvictor.97@gmail.com
GitHub: @ComputingVictor

Tem perguntas? Abra uma issue.
Gosta do projeto? Dê uma ⭐ no GitHub!

MCP-BOE

Documentação

MCP BOE 🇪🇸

🚀 Características

📋 Tabela de Conteúdos

🛠️ Instalação

Pré-requisitos

Opção 1: uvx — sem instalação (Recomendado)

Opção 2: A partir do código-fonte com uv

Opção 3: Instalação com pip

🖥️ Configuração com Claude Desktop

Com uv (Recomendado)

Com uvx

⚡ Configuração com Claude Code

Com uvx

💬 Prompts disponíveis

buscar_legislacion

analizar_norma

resumen_boe_dia

comparar_normas

🔧 Ferramentas disponíveis

📜 Legislação Consolidada (9 ferramentas)

📰 Resumos BOE/BORME (7 ferramentas)

🏛️ Tabelas Auxiliares (10 ferramentas)

🛠️ Qualidade de vida para LLMs (4 ferramentas)

📄 Leitura de PDFs (1 ferramenta)

📌 Formatos e valores úteis

⚙️ Variáveis de ambiente

💡 Exemplos de uso

Buscar legislação a partir do Python

Obter resumo do BOE

Diagnóstico de conectividade

🐛 Solução de problemas

O servidor não aparece no Claude Desktop

Erro: requires-python / incompatibilidade de versão

Erro: No module named 'mcp_boe'

A API do BOE não responde

📊 Estrutura do projeto

🤝 Contribuindo

Desenvolvimento local

📝 Changelog

v0.1.0

🔒 Segurança

📚 Referências

📄 Licença

👤 Autor

`buscar_legislacion`

`analizar_norma`

`resumen_boe_dia`

`comparar_normas`

Erro: `requires-python` / incompatibilidade de versão

Erro: `No module named 'mcp_boe'`