🇲🇦 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

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):

{
  "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)

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:

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

Service	Purpose	Registration
ACLED	Crisis/conflict data	ACLED
OpenWeatherMap	Weather data	OpenWeatherMap
HDX	Humanitarian data	HDX

🐛 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