Israel statistics mcp

MCP server that provides programmatic access to the Israeli Central Bureau of Statistics (CBS) price indices and economic data

GitHub

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

ToolDescriptionKey Parameters
get_index_topicsBrowse all available index categories and topicsperiod, searchText, lang
get_catalog_chaptersGet all index chapters (CPI, Housing, etc.)lang, pagesize
get_chapter_topicsGet topics within a specific chapterchapterId, lang
get_subject_codesGet index codes for a specific topicsubjectId, searchText
get_index_dataRetrieve historical price data for an indexcode, startPeriod, endPeriod
get_index_calculatorCalculate inflation-adjusted valuesindexCode, value, fromDate, toDate
get_main_indicesGet current main economic indicesoldFormat, lang
get_all_indicesGet comprehensive index data with filteringchapter, 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

ChapterDescriptionExamples
aConsumer Price IndexFood, clothing, housing costs
aaHousing Market IndexReal estate prices (bi-monthly)
bProducer Price Index - IndustrialManufacturing output prices
baProducer Price Index - ExportsExport prices for industry
bbProducer Price Index - ServicesService industry prices
cResidential Building InputConstruction material costs
caCommercial Building InputOffice building costs
dRoad Construction InputInfrastructure costs
eAgriculture InputAgricultural input costs
fBus InputPublic transportation costs
faPublic Minibus InputPublic 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

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

関連サーバー