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

Tool	Description	Key Parameters
`get_index_topics`	Browse all available index categories and topics	`period`, `searchText`, `lang`
`get_catalog_chapters`	Get all index chapters (CPI, Housing, etc.)	`lang`, `pagesize`
`get_chapter_topics`	Get topics within a specific chapter	`chapterId`, `lang`
`get_subject_codes`	Get index codes for a specific topic	`subjectId`, `searchText`
`get_index_data`	Retrieve historical price data for an index	`code`, `startPeriod`, `endPeriod`
`get_index_calculator`	Calculate inflation-adjusted values	`indexCode`, `value`, `fromDate`, `toDate`
`get_main_indices`	Get current main economic indices	`oldFormat`, `lang`
`get_all_indices`	Get comprehensive index data with filtering	`chapter`, `oldFormat`

🏗️ 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

Chapter	Description	Examples
`a`	Consumer Price Index	Food, clothing, housing costs
`aa`	Housing Market Index	Real estate prices (bi-monthly)
`b`	Producer Price Index - Industrial	Manufacturing output prices
`ba`	Producer Price Index - Exports	Export prices for industry
`bb`	Producer Price Index - Services	Service industry prices
`c`	Residential Building Input	Construction material costs
`ca`	Commercial Building Input	Office building costs
`d`	Road Construction Input	Infrastructure costs
`e`	Agriculture Input	Agricultural input costs
`f`	Bus Input	Public transportation costs
`fa`	Public Minibus Input	Public transport vehicle costs

⚠️ 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