uk_ons_mcp_server/README.md

MCP server for UK Office for National Statistics (ONS) API - providing access to UK government statistics

# UK ONS MCP Server

A [Model Context Protocol](https://github.com/modelcontextprotocol/specification) server that provides access to UK Office for National Statistics (ONS) data. This enables AI assistants to retrieve and analyze official UK government statistics including economic indicators, population data, and social metrics.

## Features

- 🔓 **No API Key Required** - Uses the free ONS Beta API
- 📊 **Comprehensive Data Access** - Economic, social, and demographic statistics  
- 🔍 **Smart Search** - Find datasets by keyword or topic
- 📈 **Real-time Data** - Access the latest official UK statistics
- 🌐 **Travel-Friendly** - Perfect for UK travel apps needing area demographics

## Available Tools

### Dataset Discovery
- `list_datasets()` - Get all available datasets
- `search_datasets(query)` - Search datasets by keyword
- `get_popular_datasets()` - Get commonly used datasets

### Dataset Information  
- `get_dataset_info(dataset_id)` - Detailed dataset information
- `get_dataset_editions(dataset_id)` - Available editions
- `get_dataset_download_url(dataset_id)` - Download links

### Data Access
- `get_dataset_data(dataset_id)` - Retrieve actual statistical data

## Popular Datasets

- **cpih01** - Consumer Price Inflation (CPI)
- **lms** - Labour Market Statistics  
- **regional-gdp-by-year** - Regional GDP Data
- **wellbeing-quarterly** - National Well-being Indicators
- **population-estimates-timeseries** - Population Estimates
- **house-prices** - UK House Price Statistics
- **retail-sales-index** - Retail Sales Data
- **uk-trade-info** - International Trade Statistics

## Installation

### Prerequisites
- Python 3.9+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Install with npm and pip
```bash
git clone https://github.com/dwain-barnes/uk-ons-mcp-server.git
cd uk-ons-mcp-server
npm install
npm run install-deps
```

### For development
```bash
npm run install-dev-deps
```

## Usage

### Running the Server

#### Development Mode
```bash
npm run dev
```

#### Production Mode
```bash
npm start
```

#### Testing
```bash
npm test
```

### Claude Desktop Integration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "uk-ons-statistics": {
      "command": "python",
      "args": ["/path/to/uk-ons-mcp-server/uk_ons_mcp_server/server.py"]
    }
  }
}
```

### Using with MCP Inspector

Test the server during development:
```bash
npx @modelcontextprotocol/inspector python uk_ons_mcp_server/server.py
```

## Example Queries

Ask Claude these questions once connected:

- "What datasets are available about employment?"
- "Show me the latest inflation data"
- "Get population statistics for UK regions"
- "Find datasets related to housing"
- "What's the GDP data for different UK regions?"

## API Reference

### Data Source
All data comes from the official ONS Beta API:
- **Base URL**: https://api.beta.ons.gov.uk/v1
- **Authentication**: None required
- **Rate Limits**: Reasonable usage (no official limits published)
- **Documentation**: https://developer.ons.gov.uk/

### Error Handling
The server includes comprehensive error handling for:
- Network timeouts and connection issues
- Invalid dataset IDs or parameters
- API rate limiting (if implemented)
- Data parsing errors

## Development

### Setup Development Environment
```bash
git clone https://github.com/dwain-barnes/uk-ons-mcp-server.git
cd uk-ons-mcp-server
npm install
npm run install-dev-deps
```

### Running Tests
```bash
npm test
```

### Code Formatting
```bash
npm run format
```

### Type Checking
```bash
npm run type-check
```

### Linting
```bash
npm run lint
```

## Project Structure

```
uk-ons-mcp-server/
├── uk_ons_mcp_server/
│   ├── __init__.py
│   └── server.py          # Main MCP server implementation
├── tests/
│   ├── __init__.py
│   └── test_server.py     # Unit tests
├── pyproject.toml         # Project configuration
├── README.md             # This file
├── LICENSE               # MIT License
└── .gitignore           # Git ignore patterns
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (`uv run pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [UK Office for National Statistics](https://www.ons.gov.uk/) for providing free, open access to official statistics
- [Model Context Protocol](https://github.com/modelcontextprotocol/specification) for the standardized AI integration framework
- [Anthropic](https://anthropic.com) for developing MCP and Claude

## Related Projects

- [police-uk-api-mcp-server](https://github.com/dwain-barnes/police-uk-api-mcp-server) - UK Police data MCP server
- [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations

## Disclaimer

This is an unofficial implementation and is not affiliated with, endorsed by, or sponsored by the UK Office for National Statistics. All data remains subject to ONS terms of use.