MCP ONS Server

A Model Context Protocol (MCP) server for accessing UK Office for National Statistics (ONS) data. This server enables AI assistants to query and analyze official UK statistics through a standardized interface.

Features

• 🔍 Search and discover ONS datasets
• 📊 Retrieve specific statistical observations with filtering
• 💾 Optional Redis caching for improved performance
• 🔄 Standard MCP resource format responses
• 🔐 Secure access to official UK statistics
• ⚡️ Rate limiting to comply with ONS API guidelines
• 🛡️ Input validation and sanitization
• 🏥 Health monitoring endpoint

Quick Start

Installation

# Global installation (Recommended)
npm install -g @wearelevelai/mcp-ons-server

# Or local installation
npm install @wearelevelai/mcp-ons-server

Basic Usage

# Start the server
mcp-server-ons

# Or with environment variables
ONS_USER_AGENT="my-app/1.0" mcp-server-ons

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ONS_USER_AGENT | No | mcp-ons/1.0 | User agent for ONS API requests | | REQUEST_TIMEOUT | No | 30000 | Request timeout in milliseconds | | REDIS_HOST | No | - | Redis server hostname | | REDIS_PORT | No | - | Redis server port | | REDIS_KEY | No | - | Redis password for authentication | | REDIS_TLS | No | false | Enable TLS/SSL for Redis connection |

Redis Caching (Optional)

The server includes optional Redis caching to improve performance and reduce load on the ONS API. When enabled, responses are cached for 15 minutes.

Setting up Redis

1. Install Redis:

   # macOS (using Homebrew)
   brew install redis
   brew services start redis
   
   # Ubuntu/Debian
   sudo apt update
   sudo apt install redis-server
   sudo systemctl start redis-server
   
   # Windows
   # Download from https://github.com/microsoftarchive/redis/releases

2. Configure Redis: Create a .env file or set environment variables:

   # Required Redis settings
   REDIS_HOST=localhost      # Redis server host
   REDIS_PORT=6379          # Redis server port
      
   # Optional Redis settings
   REDIS_KEY=your_password  # Redis password (if authentication is enabled)
   REDIS_TLS=false         # Enable TLS/SSL for Redis connection

3. Verify Redis Connection: The health check tool will show Redis status:

   {
     "tool": "health",
     "args": {}
   }

Available Tools

1. health

• Purpose: Check server and Redis connection status
• Parameters: None
• Returns: Health status object with Redis connection state

2. ons_list_datasets

• Purpose: Lists available ONS datasets
• Parameters:
  • keyword (optional): Search for datasets by keyword
  • limit (optional, default: 50, max: 1000): Maximum number of results
• Returns: Array of dataset objects with:
  • id: Dataset identifier
  • title: Dataset title
  • description: Dataset description (if available)
• Example:

  {
    "tool": "ons_list_datasets",
    "args": {
      "keyword": "population",
      "limit": 5
    }
  }

3. ons_get_observations

• Purpose: Gets observations from a specific dataset
• Parameters:
  • dataset_id: Dataset ID (max length: 100)
  • edition: Dataset edition (max length: 50)
  • version: Dataset version (max length: 10)
  • filters: Key-value pairs for filtering data
• Returns: Array of observation objects with values and dimensions
• Example:

  {
    "tool": "ons_get_observations",
    "args": {
      "dataset_id": "mid-year-pop-est",
      "edition": "latest",
      "version": "1",
      "filters": {
        "geography": "K02000001",
        "sex": "all",
        "age": "all"
      }
    }
  }

AI Assistant Integration

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ons-server": {
      "command": "npx",
      "args": ["-y", "@wearelevelai/mcp-ons-server"]
    }
  }
}

Best Practices for AI Assistants

1. Data Validation:

   • Always check dataset existence before requesting observations
   • Validate filter values against available options
   • Handle rate limiting errors gracefully

2. Performance Optimization:

   • Use the limit parameter to manage response size
   • Leverage Redis caching for frequent queries
   • Consider pagination for large dataset listings

3. Error Handling:

   • Handle HTTP 429 (Too Many Requests) with exponential backoff
   • Validate input parameters before making requests
   • Check health endpoint for server status

4. Security:

   • Sanitize user inputs before using in queries
   • Don't expose sensitive configuration details
   • Use appropriate user-agent strings

Development

Building from Source

git clone https://github.com/wearelevelai/mcp-ons-server.git
cd mcp-ons-server
npm install
npm run build

Running Tests

npm test

Rate Limiting

The server implements rate limiting to comply with ONS API guidelines:

• 100 requests per minute per endpoint
• Automatic retry with exponential backoff
• Redis caching helps stay within limits

Support & Contributing

• Issues: GitHub Issues
• Community: Discord
• Contributing: PRs welcome! Please open an issue first for major changes.

License

ISC

🤝 Third-Party Servers

🎖️ Official Integrations

Official integrations are maintained by companies building production ready MCP servers for their platforms.

🌎 Community Servers

A growing set of community-developed and maintained servers demonstrates various applications of MCP across different domains.

Note: Community servers are untested and should be used at your own risk. They are not affiliated with or endorsed by Anthropic.

• Office for National Statistics (ONS) - MCP server for accessing UK Office for National Statistics data, enabling AI assistants to query and analyze official UK statistics through a standardized interface. Features include dataset discovery, statistical observations retrieval, and optional Redis caching.