Dataset Viewer

What is Dataset Viewer about?

Dataset Viewer provides an MCP server that bridges the Hugging Face Dataset Viewer API with client applications. It lets users explore datasets hosted on the Hugging Face Hub, retrieve metadata, paginate rows, run SQL‑like filters, search text, and download entire splits in Parquet format.

How to use Dataset Viewer?

1. Install the Python package (requires Python 3.12+ and uv).
2. Set the environment variable HUGGINGFACE_TOKEN for private dataset access.
3. Run the server via the configured command (e.g., uv run dataset-viewer).
4. Call the exposed tools—validate, get_info, get_rows, get_first_rows, get_statistics, search_dataset, filter, and get_parquet—through the MCP client.

Key features of Dataset Viewer

• Dataset URI scheme (dataset://) for direct referencing.
• Support for multiple configurations and splits.
• Paginated row retrieval with optional page index.
• Authentication handling for private datasets via token.
• Built‑in search and SQL‑like filtering on rows.
• Automatic calculation of statistics per split.
• Ability to download entire datasets in Parquet format.

Use cases of Dataset Viewer

• Quick inspection of dataset schema and sample rows before training.
• Automated data validation pipelines that verify dataset availability and integrity.
• Exploratory data analysis (EDA) on large Hugging Face datasets without full download.
• Building custom data browsers or dashboards that query datasets on‑demand.
• Secure access to private datasets for internal research teams.

FAQ from the Dataset Viewer

Q: Do I need a Hugging Face token? A: Only when accessing private datasets; public datasets work without a token.

Q: Which Python version is required? A: Python 3.12 or newer.

Q: How do I install the server? A: Clone the repo, create a virtual environment with uv venv, activate it, and run uv add -e ..

Q: How is pagination handled? A: Use the page parameter (0‑based) with get_rows or filter to retrieve successive batches.

Q: Can I retrieve the whole dataset at once? A: Yes, via the get_parquet tool, which returns the dataset in Parquet format.

Dataset Viewer MCP Server

An MCP server for interacting with the Hugging Face Dataset Viewer API, providing capabilities to browse and analyze datasets hosted on the Hugging Face Hub.

Features

Resources

• Uses dataset:// URI scheme for accessing Hugging Face datasets
• Supports dataset configurations and splits
• Provides paginated access to dataset contents
• Handles authentication for private datasets
• Supports searching and filtering dataset contents
• Provides dataset statistics and analysis

Tools

The server provides the following tools:

1. validate

   • Check if a dataset exists and is accessible
   • Parameters:
     • dataset: Dataset identifier (e.g. 'stanfordnlp/imdb')
     • auth_token (optional): For private datasets

2. get_info

   • Get detailed information about a dataset
   • Parameters:
     • dataset: Dataset identifier
     • auth_token (optional): For private datasets

3. get_rows

   • Get paginated contents of a dataset
   • Parameters:
     • dataset: Dataset identifier
     • config: Configuration name
     • split: Split name
     • page (optional): Page number (0-based)
     • auth_token (optional): For private datasets

4. get_first_rows

   • Get first rows from a dataset split
   • Parameters:
     • dataset: Dataset identifier
     • config: Configuration name
     • split: Split name
     • auth_token (optional): For private datasets

5. get_statistics

   • Get statistics about a dataset split
   • Parameters:
     • dataset: Dataset identifier
     • config: Configuration name
     • split: Split name
     • auth_token (optional): For private datasets

6. search_dataset

   • Search for text within a dataset
   • Parameters:
     • dataset: Dataset identifier
     • config: Configuration name
     • split: Split name
     • query: Text to search for
     • auth_token (optional): For private datasets

7. filter

   • Filter rows using SQL-like conditions
   • Parameters:
     • dataset: Dataset identifier
     • config: Configuration name
     • split: Split name
     • where: SQL WHERE clause (e.g. "score > 0.5")
     • orderby (optional): SQL ORDER BY clause
     • page (optional): Page number (0-based)
     • auth_token (optional): For private datasets

8. get_parquet

   • Download entire dataset in Parquet format
   • Parameters:
     • dataset: Dataset identifier
     • auth_token (optional): For private datasets

Installation

Prerequisites

• Python 3.12 or higher
• uv - Fast Python package installer and resolver

Setup

1. Clone the repository:

git clone https://github.com/privetin/dataset-viewer.git
cd dataset-viewer

2. Create a virtual environment and install:

# Create virtual environment
uv venv

# Activate virtual environment
# On Unix:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install in development mode
uv add -e .

Configuration

Environment Variables

• HUGGINGFACE_TOKEN: Your Hugging Face API token for accessing private datasets

Claude Desktop Integration

Add the following to your Claude Desktop config file:

On Windows: %APPDATA%\Claude\claude_desktop_config.json

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dataset-viewer": {
      "command": "uv",
      "args": [
        "--directory",
        "parent_to_repo/dataset-viewer",
        "run",
        "dataset-viewer"
      ]
    }
  }
}

License

MIT License - see LICENSE for details