Israel Statistics MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to the Israeli Central Bureau of Statistics (CBS) price indices and economic data. Built with TypeScript, this server offers 8 comprehensive tools for retrieving, analyzing, and calculating Israeli economic statistics.

🐳 Installation & Usage

Docker (Recommended)

// .mcp.json
{
  "israel-statistics-mcp": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "reuvenaor/israel-statistics-mcp:latest"]
  }
}

NPX

// .mcp.json
{
  "israel-statistics-mcp": {
    "command": "npx",
    "args": ["@reuvenorg/israel-statistics-mcp"]
  }
}

Claude Desktop Integration

# Quick setup
claude mcp add --scope project israel-statistics-mcp npx @reuvennaor85/israel-statistics-mcp

🚀 Features

📊 Comprehensive Economic Data Access

• Consumer Price Index (CPI) - General and detailed price indices
• Housing Market Index - Real estate prices with bi-monthly updates
• Producer Price Indices - Industrial, exports, and services
• Specialized Indices - Construction, agriculture, transportation, and more
• Price Linkage Calculator - Inflation adjustment calculations

🛡️ Enterprise-Grade Architecture

• Type-Safe Validation - Complete Zod schema validation for all inputs/outputs
• Rate Limiting - Built-in protection (5 concurrent operations max)
• Error Handling - Comprehensive CBS API error handling and retry logic
• Multi-Format Support - JSON and XML response parsing
• Housing Market Warnings - Automatic notifications for bi-monthly provisional data

🔄 Advanced Data Processing

• XML/JSON Transformation - Seamless conversion from CBS API formats
• Statistical Calculations - Automatic averages, counts, and summaries
• Date Range Filtering - Flexible period selection (monthly/quarterly)
• Search & Discovery - Full-text search across indices and topics
• Pagination Support - Handle large datasets efficiently (up to 1000 items/page)

📋 Available MCP Tools

🏗️ Architecture

src/
├── index.ts                    # MCP server entry point with tool registration
├── mcp/
│   ├── handlers/              # 8 MCP tool handlers
│   │   ├── getIndexTopics.ts     # Browse available indices
│   │   ├── getCatalogChapters.ts # Get index chapters
│   │   ├── getChapterTopics.ts   # Topics by chapter
│   │   ├── getSubjectCodes.ts    # Index codes by topic
│   │   ├── getIndexData.ts       # Historical price data
│   │   ├── getIndexCalculator.ts # Inflation calculator
│   │   ├── getMainIndices.ts     # Main indices (current + by period)
│   │   └── getAllIndices.ts      # All indices with filtering
│   └── helpers/
│       ├── fetcher.ts            # Secure CBS API client with XML/JSON parsing
│       └── housingWarnings.ts    # Housing market data warnings
├── schemas/                   # Type-safe Zod validation schemas
│   ├── request.schema.ts         # Input validation schemas
│   ├── response.schema.ts        # Output validation schemas
│   ├── base.schema.ts           # Reusable object schemas
│   └── shared.schema.ts                # Common enums and types
└── utils/
    ├── registry-security.ts      # Security utilities
    └── spinner.ts               # MCP progress notifications

🔒 Security Features

• Rate Limiting: Maximum 5 concurrent operations
• Input Validation: Comprehensive Zod schema validation
• URL Validation: Allowlist-based registry URL security
• Error Sanitization: Safe error message handling
• Timeout Protection: 30-second HTTP request timeouts

📝 Schema Architecture

📊 CBS API Coverage

The server implements complete coverage of the CBS Israel Statistics API:

Index Discovery Endpoints

• GET /index/catalog/tree → get_index_topics
• GET /index/catalog/catalog → get_catalog_chapters
• GET /index/catalog/chapter → get_chapter_topics
• GET /index/catalog/subject → get_subject_codes

Data Retrieval Endpoints

• GET /index/data/price → get_index_data
• GET /index/data/calculator/{id} → get_index_calculator
• GET /index/data/price_selected → get_main_indices
• GET /index/data/price_selected_b → get_main_indices_by_period
• GET /index/data/price_all → get_all_indices

Supported Index Categories

⚠️ Housing Price Index Special Considerations

The server automatically detects and warns about Housing Price Index data:

• Bi-monthly Publication: Updates every 2 months vs. monthly for other indices
• Temporal Lag: Data reflects transactions from 2-3 months ago vs. 3-4 months ago
• Provisional Data: Last 3 indices may be updated when additional reports arrive
• Linkage Warnings: Automatic recommendations against using provisional periods

🧪 Testing & Quality Assurance

Comprehensive Test Suite

• Unit Tests: Complete handler coverage with Vitest
• Integration Tests: Real CBS API integration tests
• Mock Testing: Isolated handler testing with mocked dependencies
• Error Handling: Network error and API error simulation
• Schema Validation: Input/output validation testing

Code Quality Tools

• TypeScript: Strict type checking with no any types
• ESLint: Modern flat config with TypeScript rules
• Prettier: Consistent code formatting
• Zod: Runtime type validation and inference

Development Commands

# Development
pnpm dev              # Watch mode development
pnpm build           # Production build
pnpm typecheck       # TypeScript validation

# Testing
pnpm test            # Run all tests
pnpm test:dev        # Development mode testing

# Quality
pnpm lint            # Lint code
pnpm lint:fix        # Fix linting issues
pnpm format:check    # Check formatting
pnpm format:write    # Apply formatting

# Docker
docker build -t reuvenaor/israel-statistics-mcp:latest -f Dockerfile .

🔧 Development

Project Structure

• TypeScript ESM: Modern ES modules with TypeScript
• pnpm: Fast, efficient package management
• tsup: Fast TypeScript bundler with ESM output
• Docker: Multi-stage builds for optimized containers
• Vitest: Fast unit testing framework

Key Dependencies

• @modelcontextprotocol/sdk: MCP server implementation
• zod: Type-safe validation and schema inference
• node-fetch: HTTP client for CBS API calls
• xml2js: XML response parsing
• typescript: Type system and compilation

Configuration Files

• tsconfig.json: TypeScript configuration with strict settings
• eslint.config.js: Modern ESLint flat configuration
• prettier.config.cjs: Code formatting rules
• vitest.config.ts: Test framework configuration
• tsup.config.ts: Build tool configuration
• Dockerfile: Multi-stage container build

📈 Performance & Scalability

• Rate Limiting: 5 concurrent operations maximum
• Efficient Parsing: Optimized XML/JSON transformation
• Memory Management: Streaming for large datasets
• Caching: Schema validation caching
• Error Recovery: Graceful degradation and retry logic

📝 API Response Examples

Index Topics Discovery

// Input
{ lang: "en", searchText: "housing", period: "M" }

// Output
{
  topics: [
    {
      chapterId: "aa",
      chapterName: "Housing Market Index",
      subject: [
        {
          subjectId: 123,
          subjectName: "Apartment Prices",
          code: [
            {
              codeId: 180010,
              codeName: "Housing Price Index - General"
            }
          ]
        }
      ]
    }
  ],
  summary: "Found 15 index codes. ⚠️ Housing Price Index: This is a bi-monthly index..."
}

Price Linkage Calculation

// Input
{
  indexCode: 120010,
  value: 1000,
  fromDate: "01-01-2020",
  toDate: "01-01-2024"
}

// Output
{
  request: { code: 120010, sum: 1000, from_date: "2020-01-01", to_date: "2024-01-01" },
  answer: {
    from_value: 1000,
    to_value: 1155.2,
    change_percent: 15.52,
    base_year: "2022"
  },
  summary: "Linked 1000 from 2020-01-01 to 2024-01-01: 1155.2 (15.52% change)"
}

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Repository: https://github.com/reuvenaor/israel-statistics-mcp
• Docker Hub: reuvenaor/israel-statistics-mcp
• NPM Package: @reuvenorg/israel-statistics-mcp
• CBS API Documentation: Israel Central Bureau of Statistics
• MCP Protocol: Model Context Protocol Specification

Built with ❤️ for the Israeli tech community and economic research