Spain Ai Kit

🏛️ Spain AI Kit 🇪🇸

Plaza de España, Sevilla — AI-generated hero image

[!NOTE] This is a community-driven open source project and is not affiliated with, endorsed by, or connected to the Spanish government or any official Spanish institutions. All data is sourced from public APIs published by their respective agencies.

🌍 Spain's Open Data Landscape

Spain runs one of Europe's most extensive public data infrastructures. The Boletín Oficial del Estado traces its lineage to the Gaceta de Madrid — first published in 1661 — and today publishes every national law, royal decree, and official announcement as structured open data. The Instituto Nacional de Estadística exposes thousands of statistical series through a public JSON API. The Catastro offers free cadastral lookups for every property in the country. AEMET serves forecasts for more than 8,000 municipalities across Spain's 17 autonomous communities and two autonomous cities.

The problem: most of this is locked behind XML envelopes, SOAP endpoints, Spanish-only documentation, and idiosyncratic JSON-stat formats. Spain AI Kit makes it usable from an AI assistant in one line of config.

• 12,000+ consolidated Spanish laws queryable as Markdown (national + all 17 autonomous communities)
• 70+ statistical operations from INE — demographics, economics, employment, housing, tourism
• 50 provinces, 8,000+ municipalities covered for address and cadastral lookups
• Daily BOE gazette searchable by date, keyword, subject, or legal scope
• Weather, UV, fire risk, and beach forecasts for the whole country

📖 What is Spain AI Kit?

Spain AI Kit is a collection of MCP (Model Context Protocol) servers that connect AI assistants — Claude Desktop, Claude Code, Cursor, and anything else that speaks MCP — directly to Spanish government open data APIs. No scraping, no API wrangling, no translating Spanish JSON-stat by hand.

🎯 What is MCP?

Model Context Protocol is an open standard that lets AI applications plug into external data sources and tools through a consistent interface. Each Spain AI Kit package is a standalone MCP server you can install and mount independently — use one, use them all, or compose them with other MCP servers.

Inspired by estonia-ai-kit by Stefano Amorelli.

📦 What's Included

🗺️ Roadmap

🚀 Quick Start

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "spain-ine": {
      "command": "npx",
      "args": ["@spain-ai-kit/ine-mcp-server"]
    },
    "spain-boe": {
      "command": "npx",
      "args": ["@spain-ai-kit/boe-mcp-server"]
    },
    "spain-catastro": {
      "command": "npx",
      "args": ["@spain-ai-kit/catastro-mcp-server"]
    },
    "spain-aemet": {
      "command": "npx",
      "args": ["@spain-ai-kit/aemet-mcp-server"],
      "env": {
        "AEMET_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add spain-ine -- npx @spain-ai-kit/ine-mcp-server
claude mcp add spain-boe -- npx @spain-ai-kit/boe-mcp-server
claude mcp add spain-catastro -- npx @spain-ai-kit/catastro-mcp-server
claude mcp add spain-aemet --env AEMET_API_KEY=your-key -- npx @spain-ai-kit/aemet-mcp-server

[!TIP] AEMET API key — The weather server requires a free API key. Get one in 30 seconds at opendata.aemet.es — just enter your email. The other three servers need zero setup.

Try it

Once configured, ask your AI assistant things like:

• 💬 "What is the current CPI in Spain?"
• 💬 "Search Spanish law about data protection and summarise the most recent changes"
• 💬 "Show me employment statistics for Valencia province over the last 5 years"
• 💬 "What does the foreigners law say about residence permits for UK nationals?"
• 💬 "What property is at Calle Gran Vía 1, Madrid? Get me the cadastral reference"
• 💬 "Is there a weather alert for Andalucía today?"
• 💬 "What's the UV index in Málaga and should I put sunscreen on the kids?"
• 💬 "Find properties within 100 metres of these coordinates"

For detailed usage examples, tips, and troubleshooting, see the User Guide.

🔧 MCP Servers

INE — National Statistics

@spain-ai-kit/ine-mcp-server — connects to the Instituto Nacional de Estadística JSON API. 70+ statistical operations covering demographics, economics, employment, housing, tourism, and more.

BOE — Legislation

@spain-ai-kit/boe-mcp-server — connects to the Boletín Oficial del Estado open data API and the legalize-es legislation corpus.

Catastro — Land Registry

@spain-ai-kit/catastro-mcp-server — connects to the Dirección General del Catastro web services. Property lookups, address resolution, and geocoding for all of Spain.

AEMET — Weather

@spain-ai-kit/aemet-mcp-server — connects to AEMET OpenData for weather forecasts, observations, and alerts across Spain.

📚 Legislation Corpus

The BOE server optionally integrates with legalize-es, which provides the full consolidated text of 12,000+ Spanish laws as Markdown files with Git-tracked reform history.

To enable corpus search, clone with submodules:

git clone --recurse-submodules https://github.com/aplaceforallmystuff/spain-ai-kit.git
# Or if already cloned:
git submodule update --init

Coverage: national legislation + all 17 autonomous communities and 2 autonomous cities — Andalucía, Aragón, Asturias, Baleares, Canarias, Cantabria, Castilla-La Mancha, Castilla y León, Catalunya, Ceuta, Extremadura, Galicia, La Rioja, Madrid, Melilla, Murcia, Navarra, País Vasco, Valencia.

⚡ Technical Stack

🛠️ Project Structure

spain-ai-kit/
├── mcp/
│   ├── ine/              # INE Statistics MCP server
│   ├── boe/              # BOE Legislation MCP server
│   ├── catastro/         # Catastro Land Registry MCP server
│   └── aemet/            # AEMET Weather MCP server
├── packages/
│   └── shared/           # Shared utilities (HTTP client, XML parser, validators)
├── corpus/
│   └── legalize-es/      # Git submodule — legislation as Markdown
├── docs/
│   └── GUIDE.md          # User guide with examples and troubleshooting
├── nx.json
└── tsconfig.base.json

🧑‍💻 Development

Prerequisites

• Node.js 20+
• Git (with submodule support for the legislation corpus)

Setup

# Clone with submodules
git clone --recurse-submodules https://github.com/aplaceforallmystuff/spain-ai-kit.git
cd spain-ai-kit

# Install all workspace dependencies
npm install

# Build all packages (shared first, then MCP servers)
npm run build

# Run tests
npm test

# Format with Prettier
npm run format

# Watch mode for development
npm run dev

Conventions

• npm scope: @spain-ai-kit/*
• MCP servers: @spain-ai-kit/{service}-mcp-server
• Shared code: @spain-ai-kit/shared
• TypeScript strict mode, ES2022 target
• All tool handlers wrapped with wrapToolHandler (unified error handling)
• All user inputs validated before API calls (validators live in @spain-ai-kit/shared)
• Rate limiting on all API clients (maxRequestsPerSecond)

🔗 Spanish Government Resources

• 🏛️ BOE — Boletín Oficial del Estado — Official State Gazette
• 📊 INE — Instituto Nacional de Estadística — National Statistics Institute
• 🏠 Catastro — Dirección General del Catastro — Land registry
• 🌤️ AEMET — Agencia Estatal de Meteorología — State Meteorological Agency
• 📂 datos.gob.es — National open data portal
• 🧾 AEAT — Agencia Tributaria — Tax agency
• 💼 SEPE — Servicio Público de Empleo Estatal — Employment service

🤝 Contributing

PRs and issues welcome. See CONTRIBUTING.md for guidelines on adding new MCP servers and contributing to existing ones.

Fork → Branch → Commit → Push → PR

Need help building or securing MCP servers?

I build and maintain MCP servers like these, and I review AI and agent setups for security. If your team needs a custom server, an integration, or a security review of one you already run, see jimchristian.net/work or book a discovery session.

⚖️ License

MIT — see LICENSE for details.

Legislative content sourced from public government APIs is in the public domain. The legalize-es corpus is distributed under its own license — see that repository for details.