🇲🇦 Morocco Open Data MCP Server

A comprehensive Model Context Protocol (MCP) server providing unified access to Moroccan government data sources, financial markets, geographic information, and more.

📋 Table of Contents

• Features

• Quick Start

• Installation

• Configuration

• Available Tools

• Usage Examples

• Data Sources

• Deployment

• Development

• API Keys

• Troubleshooting

• Contributing

• License

✨ Features

🏛️ National Open Data

• Access to data.gov.ma - Morocco's national open data portal

• Search datasets in Arabic, French, and English

• Browse by organization, tags, and categories

• Download resources in various formats (CSV, JSON, XML, etc.)

💰 Financial & Macroeconomic Data

• Bank Al-Maghrib (Central Bank)

  • Exchange rates (daily updates)

  • Key interest rates and monetary policy

  • Inflation and consumer price indices

  • Money supply aggregates (M1, M2, M3)

  • Treasury bills auction results

  • Foreign reserves data

• Casablanca Stock Exchange (BVC)

  • Real-time stock quotes

  • Market indices (MASI, MASIX, etc.)

  • Company information and financials

  • Government and corporate bonds

  • Market statistics and trading data

🌍 International Data

• World Bank Indicators

  • GDP and economic growth

  • Population and demographics

  • Poverty and social indicators

  • Trade and balance of payments

  • Environmental statistics

🕌 Islamic Services

• Prayer times for all major Moroccan cities

• Weekly and monthly prayer schedules

• Qibla direction calculations

• Hijri calendar integration

🗺️ Geography & GIS

• Administrative divisions (12 regions)

• City coordinates and metadata

• Searchable city database

• Regional information in multiple languages

🤝 Humanitarian & Crisis Data

• Humanitarian Data Exchange (HDX) integration

• Emergency response datasets

• Refugee and displacement data

• Health and education statistics

🌱 Climate & Environment

• Climate data and weather patterns

• Environmental indicators

• CO2 emissions tracking

• Renewable energy statistics

🚀 Quick Start

Prerequisites

• Node.js 18.0 or higher

• npm or yarn

• Claude Desktop (for MCP integration)

1. Clone the Repository

cd "MoroccoOpenData MCP"

2. Install Dependencies

npm install

3. Build the Server

npm run build

4. Configure Environment

cp .env.example .env
# Edit .env and add your API keys

5. Test the Server

npm test

6. Run the Server

# Development mode (with hot reload)
npm run dev

# Production mode
npm start

📦 Installation

Using npm

npm install -g morocco-open-data-mcp

From Source

git clone https://github.com/kcbdev/morocco-open-data-mcp.git
cd morocco-open-data-mcp
npm install
npm run build

Using Docker

# Build the image
docker build -t morocco-open-data-mcp .

# Run the container
docker run -d \
  --name morocco-mcp \
  -e MCP_TRANSPORT=http \
  -e MCP_PORT=3000 \
  -e BAM_KEY_CHANGES=your_key \
  morocco-open-data-mcp

Using Docker Compose

# Create .env file with your API keys
cp .env.example .env

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

⚙️ Configuration

Environment Variables

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

For Local Development (stdio transport):

{
  "mcpServers": {
    "morocco-open-data": {
      "command": "node",
      "args": ["/home/kcb/Work/LABS/MOPD/MoroccoOpenData MCP/dist/index.js"],
      "env": {
        "BAM_KEY_CHANGES": "your_key_here",
        "BAM_KEY_OBLIGATIONS": "your_key_here",
        "BAM_KEY_TBILLS": "your_key_here"
      }
    }
  }
}

For Remote Server (HTTP SSE transport):

{
  "mcpServers": {
    "morocco-open-data": {
      "url": "https://morocco-opendata-mcp.kcb.ma",
      "transportType": "sse"
    }
  }
}

Using mcp-remote:

{
  "mcpServers": {
    "morocco-open-data": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest"],
      "env": {
        "MCP_SERVER_URL": "https://morocco-opendata-mcp.kcb.ma/sse"
      }
    }
  }
}

🛠️ Available Tools

Open Data (data.gov.ma)

Financial & Macroeconomic

Capital Markets

Geography & GIS

Prayer Times

Humanitarian & Crisis

Climate & Environment

Knowledge Graph

📖 Usage Examples

Example 1: Search for Economic Datasets

Search for datasets about Morocco's economy on data.gov.ma

Example 2: Get Current Exchange Rates

What's the current exchange rate for EUR to MAD?
Show me all exchange rates from Bank Al-Maghrib

Example 3: Stock Market Information

Get me the current stock price for Attijariwafa Bank
Show me today's market summary from Casablanca Stock Exchange
What are the top gainers today?

Example 4: Prayer Times

What are the prayer times for today in Marrakech?
When is the next prayer in Rabat?
Show me the weekly prayer schedule for Casablanca

Example 5: Economic Indicators

Get Morocco's GDP growth rate for the last 5 years
Show me the current inflation rate
What's the unemployment rate in Morocco?

Example 6: Geographic Data

List all regions of Morocco with their capitals
What are the coordinates of Fes?
Search for cities in the Souss-Massa region

📊 Data Sources

Tier 1 - Native REST APIs

Tier 2 - Structured Downloads

Tier 3 - International Sources

🚢 Deployment

Production Deployment with Docker

1. Build the production image:

docker build -t morocco-open-data-mcp:latest --target production .

2. Run with environment variables:

docker run -d \
  --name morocco-mcp \
  --restart unless-stopped \
  -e NODE_ENV=production \
  -e MCP_TRANSPORT=http \
  -e MCP_PORT=3000 \
  -e BAM_KEY_CHANGES=your_key \
  -e BAM_KEY_OBLIGATIONS=your_key \
  -e BAM_KEY_TBILLS=your_key \
  -e CACHE_TTL_DEFAULT=3600 \
  -e RATE_LIMIT_DEFAULT=60 \
  morocco-open-data-mcp:latest

3. Monitor the container:

docker logs -f morocco-mcp
docker stats morocco-mcp

Coolify Deployment

For deployment on Coolify (https://coolify.kcb.ma):

1. Create new resource from Git repository

2. Repository: https://github.com/kcbdev/morocco-open-data-mcp

3. Branch: main

4. Domain: morocco-opendata-mcp.kcb.ma

5. Environment Variables:

   MCP_TRANSPORT=http
   MCP_PORT=3000
   MCP_HOST=0.0.0.0
   NODE_ENV=production
   BAM_KEY_CHANGES=your_key
   BAM_KEY_OBLIGATIONS=your_key
   BAM_KEY_TBILLS=your_key

Kubernetes Deployment (Optional)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: morocco-mcp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: morocco-mcp
  template:
    metadata:
      labels:
        app: morocco-mcp
    spec:
      containers:
      - name: mcp-server
        image: ghcr.io/kcbdev/morocco-open-data-mcp:latest
        env:
        - name: NODE_ENV
          value: "production"
        - name: MCP_TRANSPORT
          value: "http"
        - name: BAM_KEY_CHANGES
          valueFrom:
            secretKeyRef:
              name: mcp-secrets
              key: bam-key-changes
        resources:
          limits:
            cpu: "1"
            memory: "512Mi"
          requests:
            cpu: "250m"
            memory: "128Mi"

👨‍💻 Development

Project Structure

morocco-open-data-mcp/
├── src/
│   ├── clients/          # API clients for each data source
│   │   ├── ckan.ts       # data.gov.ma client
│   │   ├── bam.ts        # Bank Al-Maghrib client
│   │   ├── worldbank.ts  # World Bank client
│   │   ├── bvc.ts        # Casablanca Stock Exchange client
│   │   ├── prayer.ts     # Prayer times client
│   │   ├── geo.ts        # Geography/GIS client
│   │   ├── hdx.ts        # Humanitarian Data Exchange client
│   │   └── weather.ts    # Weather API client
│   ├── lib/              # Core utilities
│   │   ├── cache.ts      # Caching layer
│   │   ├── rateLimiter.ts # Rate limiting
│   │   ├── arabic.ts     # Arabic text processing
│   │   └── errors.ts     # Error handling
│   ├── sync/             # Data synchronization jobs
│   ├── index.ts          # Main server entry point
│   └── test.ts           # Test suite
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
├── claude_desktop_config.json
└── README.md

Development Commands

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run sync jobs manually
npm run sync

# Start production server
npm start

Running Tests

# Run all tests
npm test

# Run tests with external APIs disabled
SKIP_EXTERNAL_APIS=true npm test

# Run specific test file
npx tsx src/test.ts

🔑 API Keys

Required API Keys

Bank Al-Maghrib (BAM)

• Registration: Visit Bank Al-Maghrib and request API access

• Endpoints: Exchange rates, treasury bills, government obligations

• Rate Limits: 30 requests/minute

World Bank

• Registration: World Bank Data Connect

• Free tier: 60 requests/minute

• Documentation: World Bank API Docs

Optional API Keys

🐛 Troubleshooting

Common Issues

1. "Module not found" errors

# Rebuild the project
rm -rf dist/
npm run build

2. API rate limit errors

• Check your rate limit status in logs

• Increase RATE_LIMIT_DEFAULT in .env

• Implement request caching

3. BAM API authentication errors

• Verify API keys are correct

• Check if keys have expired

• Ensure keys have correct permissions

4. Claude Desktop integration issues

• Verify path to dist/index.js is correct

• Check Claude Desktop logs

• Restart Claude Desktop after config changes

5. SSE Connection Failed

• Ensure MCP_TRANSPORT=http is set in environment variables

• Verify the server is running in HTTP mode

• Check firewall allows connections to port 3000

Debug Mode

Enable verbose logging:

NODE_ENV=development DEBUG=* npm run dev

Health Checks

# Check if server is running (HTTP mode)
curl https://morocco-opendata-mcp.kcb.ma/health

# Check if server is running (local stdio mode)
node -e "console.log('MCP server healthy')"

# The server will log status of all data sources on startup

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

1. Fork the repository: https://github.com/kcbdev/morocco-open-data-mcp

2. Create a feature branch: git checkout -b feature/your-feature

3. Make your changes

4. Run tests: npm test

5. Commit your changes: git commit -am 'Add new feature'

6. Push to the branch: git push origin feature/your-feature

7. Submit a pull request

Code Style

• Follow TypeScript best practices

• Use ESLint rules (coming soon)

• Write meaningful commit messages

• Add tests for new features

• Update documentation

Areas for Contribution

• Additional data sources (ministries, agencies)

• More geographic data (provinces, communes)

• Historical data archives

• Data visualization tools

• Arabic/French language improvements

• Performance optimizations

• Documentation translations

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

See the LICENSE file for details.

What This Means:

• ✅ You CAN: Share, copy, redistribute, adapt, and build upon this material

• ✅ You MUST: Give appropriate credit, provide a link to the license, and indicate if changes were made

• ❌ You CANNOT: Use this material for commercial purposes

• ❌ You CANNOT: Apply legal terms or technological measures that restrict others from doing anything the license permits

For commercial licensing inquiries, contact: oss@kcb.ma

📞 Support

• Issues: GitHub Issues

• Email: oss@kcb.ma

🙏 Acknowledgments

• Bank Al-Maghrib - For providing financial and economic data

• data.gov.ma - Morocco's national open data portal

• World Bank - For development indicators and statistics

• Casablanca Stock Exchange - For market data

• Aladhan API - For prayer times services

• MCP Project - For the Model Context Protocol framework

Built with ❤️ for Morocco's open data community

Morocco Open Data MCP Server v1.0.0
Live Deployment: https://morocco-opendata-mcp.kcb.ma
Source Code: https://github.com/kcbdev/morocco-open-data-mcp