# 🇲🇦 Morocco Open Data MCP Server

A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server providing unified access to Moroccan government data sources, financial markets, geographic information, and more.

## 📋 Table of Contents

- [Features](#-features)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Available Tools](#-available-tools)
- [Usage Examples](#-usage-examples)
- [Data Sources](#-data-sources)
- [Deployment](#-deployment)
- [Development](#-development)
- [API Keys](#-api-keys)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

## ✨ Features

### 🏛️ National Open Data
- Access to [data.gov.ma](https://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
```bash
cd "MoroccoOpenData MCP"
```

### 2. Install Dependencies
```bash
npm install
```

### 3. Build the Server
```bash
npm run build
```

### 4. Configure Environment
```bash
cp .env.example .env
# Edit .env and add your API keys
```

### 5. Test the Server
```bash
npm test
```

### 6. Run the Server
```bash
# Development mode (with hot reload)
npm run dev

# Production mode
npm start
```

## 📦 Installation

### Using npm
```bash
npm install -g morocco-open-data-mcp
```

### From Source
```bash
git clone https://github.com/kcbdev/morocco-open-data-mcp.git
cd morocco-open-data-mcp
npm install
npm run build
```

### Using Docker
```bash
# 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
```bash
# 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

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `auto` |
| `MCP_PORT` | HTTP server port (when using HTTP transport) | `3000` |
| `MCP_HOST` | HTTP server host | `0.0.0.0` |
| `BAM_KEY_CHANGES` | Bank Al-Maghrib API key for exchange rates | Required for BAM data |
| `BAM_KEY_OBLIGATIONS` | BAM API key for government obligations | Required for obligations |
| `BAM_KEY_TBILLS` | BAM API key for treasury bills | Required for T-bills |
| `WORLD_BANK_API_KEY` | World Bank API key | Optional (some endpoints) |
| `ACLED_API_KEY` | ACLED API key for crisis data | Optional |
| `OPENWEATHER_API_KEY` | OpenWeatherMap API key | Optional |
| `CACHE_TTL_DEFAULT` | Default cache TTL (seconds) | 3600 |
| `CACHE_TTL_SHORT` | Short-term cache TTL (seconds) | 300 |
| `CACHE_TTL_LONG` | Long-term cache TTL (seconds) | 86400 |
| `RATE_LIMIT_DEFAULT` | Default rate limit (req/min) | 60 |
| `RATE_LIMIT_STRICT` | Strict rate limit (req/min) | 10 |

### 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):
```json
{
  "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):
```json
{
  "mcpServers": {
    "morocco-open-data": {
      "url": "https://morocco-opendata-mcp.kcb.ma",
      "transportType": "sse"
    }
  }
}
```

#### Using mcp-remote:
```json
{
  "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)
| Tool | Description |
|------|-------------|
| `search_datasets` | Search for datasets on Morocco's open data portal |
| `get_dataset` | Get detailed information about a specific dataset |
| `list_organizations` | List all data-publishing organizations |
| `search_by_tag` | Search datasets by tag |

### Financial & Macroeconomic
| Tool | Description |
|------|-------------|
| `get_exchange_rates` | Get current exchange rates from Bank Al-Maghrib |
| `get_interest_rates` | Get key interest rates and monetary policy rates |
| `get_inflation_data` | Get inflation and CPI data |
| `get_money_supply` | Get money supply aggregates (M1, M2, M3) |
| `get_treasury_bills` | Get treasury bills auction results |
| `get_world_bank_indicators` | Get World Bank development indicators |
| `get_morocco_economic_summary` | Get comprehensive economic summary |

### Capital Markets
| Tool | Description |
|------|-------------|
| `get_stock_quotes` | Get stock quotes from Casablanca Stock Exchange |
| `get_market_summary` | Get today's market summary |
| `get_market_indices` | Get market indices (MASI, MASIX, etc.) |
| `get_bond_quotes` | Get government and corporate bond quotes |
| `get_company_info` | Get detailed company information |

### Geography & GIS
| Tool | Description |
|------|-------------|
| `get_morocco_regions` | Get all administrative regions of Morocco |
| `get_city_coordinates` | Get coordinates for Moroccan cities |
| `search_cities` | Search for cities by name or region |

### Prayer Times
| Tool | Description |
|------|-------------|
| `get_prayer_times` | Get prayer times for a specific date |
| `get_weekly_prayer_times` | Get prayer times for the next 7 days |
| `get_next_prayer` | Get the next upcoming prayer time |
| `list_prayer_cities` | List all available Moroccan cities |

### Humanitarian & Crisis
| Tool | Description |
|------|-------------|
| `get_humanitarian_datasets` | Search humanitarian datasets from HDX |

### Climate & Environment
| Tool | Description |
|------|-------------|
| `get_climate_data` | Get climate and weather data |
| `get_environmental_indicators` | Get environmental indicators (CO2, renewable energy, etc.) |

### Knowledge Graph
| Tool | Description |
|------|-------------|
| `search_knowledge_graph` | Search the Morocco knowledge graph |
| `get_data_sources` | Get list of all available data sources |

## 📖 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
| Source | Type | Status |
|--------|------|--------|
| data.gov.ma | CKAN API | ✅ Active |
| Bank Al-Maghrib | REST API | ✅ Active |
| Casablanca Stock Exchange | REST API | ✅ Active |
| World Bank | REST API | ✅ Active |
| Aladhan (Prayer Times) | REST API | ✅ Active |

### Tier 2 - Structured Downloads
| Source | Type | Status |
|--------|------|--------|
| HCP (High Commission for Planning) | Portal | 🔄 Pending |
| Ministry of Economy & Finance | Portal | 🔄 Pending |
| Ministry of Health | Portal | 🔄 Pending |

### Tier 3 - International Sources
| Source | Type | Status |
|--------|------|--------|
| Humanitarian Data Exchange | API | 🔄 Pending |
| ACLED (Crisis Data) | API | 🔄 Pending |
| OpenWeatherMap | API | 🔄 Pending |

## 🚢 Deployment

### Production Deployment with Docker

1. **Build the production image:**
```bash
docker build -t morocco-open-data-mcp:latest --target production .
```

2. **Run with environment variables:**
```bash
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:**
```bash
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)

```yaml
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

```bash
# 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

```bash
# 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](https://www.bkam.ma/en/Statistical-Data) and request API access
- **Endpoints:** Exchange rates, treasury bills, government obligations
- **Rate Limits:** 30 requests/minute

#### World Bank
- **Registration:** [World Bank Data Connect](https://datahelpdesk.worldbank.org/dataconnect/)
- **Free tier:** 60 requests/minute
- **Documentation:** [World Bank API Docs](https://datahelpdesk.worldbank.org/knowledgebase/topics/125589)

### Optional API Keys

| Service | Purpose | Registration |
|---------|---------|--------------|
| ACLED | Crisis/conflict data | [ACLED](https://acleddata.com/api/) |
| OpenWeatherMap | Weather data | [OpenWeatherMap](https://openweathermap.org/api) |
| HDX | Humanitarian data | [HDX](https://data.humdata.org/) |

## 🐛 Troubleshooting

### Common Issues

#### 1. "Module not found" errors
```bash
# 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:
```bash
NODE_ENV=development DEBUG=* npm run dev
```

### Health Checks

```bash
# 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](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](https://github.com/kcbdev/morocco-open-data-mcp/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