npm package: @fluid-data/mcp-datahub
Description: MCP server for the Fluid Datahub sports data API
Author: Fluid Data Services
Latest version: 0.2.0

# Fluid Datahub MCP Server

Query the Fluid Datahub sports data API from Claude Desktop using natural language.

Covers 100+ sports: football, rugby, tennis, motorsport, cycling, and more.

## Quick Start

### 1. Install

Make sure [Node.js](https://nodejs.org/) 18+ is installed on your machine.

### 2. Configure Claude Desktop

Open **Settings > Developer > Edit Config** (or edit `claude_desktop_config.json` directly).

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the `fluid-datahub` server:

```json
{
  "mcpServers": {
    "fluid-datahub": {
      "command": "npx",
      "args": ["-y", "@fluid-data/mcp-datahub"],
      "env": {
        "DATAHUB_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Replace `your-api-key-here` with the API key provided by Fluid Data Services.

To target the staging environment, add:
```json
"DATAHUB_BASE_URL": "https://api.fluiddataservices.com/staging/"
```

### 3. Restart Claude Desktop

Quit and reopen Claude Desktop. In a **new conversation**, you should see the Datahub tools available.

## What You Can Ask

Here are example prompts to get started:

### Explore the catalog
- "What sports are available?"
- "List all football competitions"
- "What seasons are available for the Champions League?"
- "Show me the teams in La Liga 2025"
- "Who are the players in the France rugby team this season?"

### Events & schedules
- "What matches are happening today?"
- "Show me upcoming Premier League fixtures"
- "What were yesterday's results?"
- "Give me details on this match: `<event-uuid>`"

### Standings & rankings
- "Show the Ligue 1 standings"
- "What are the live Champions League standings?"
- "Who are the top 10 scorers in Serie A this season?"
- "Show me the top 5 teams by goals scored in the Premier League"

### Play-by-play
- "Show me the timeline of this match: `<event-uuid>`"

### Multi-language
All prompts work with localization. Just ask in your language or specify:
- "Liste les compétitions de football" (French)
- "Mostra a classificação da Liga Portugal" (Portuguese)

## Available Tools

| Tool | What it does |
|------|-------------|
| `list_sports` | List all sports in the Datahub |
| `list_competitions` | List competitions, optionally filtered by sport |
| `list_seasons` | List available seasons for a competition |
| `list_teams` | List teams for a competition and season |
| `list_actors` | List players/drivers, optionally filtered by team |
| `search_events` | Find events by date — all, upcoming schedule, or past results |
| `get_event` | Get full details of a specific event |
| `get_standings` | Team or player standings, with live support |
| `get_stats` | Rankings and top N player/team statistics |
| `get_timeline` | Play-by-play timeline of an event |

## Tips

- **Start broad, then narrow down.** Ask for sports first, then competitions, then seasons — Claude will chain the calls for you.
- **Use natural dates.** "yesterday", "next Saturday", "March 15" all work — Claude converts them to the right format.
- **Combine questions.** "Compare the top scorers of La Liga and Premier League" will trigger multiple tool calls automatically.
- **Data depth varies.** Not all competitions have the same number of historical seasons available.

## Troubleshooting

| Problem | Solution |
|---------|----------|
| No tools visible | Restart Claude Desktop, open a **new** conversation |
| "Server disconnected" | Check that Node.js 18+ is installed and `npx` is in your PATH |
| "Datahub API error 403" | Verify your API key is correct |
| Missing data | Some competitions have limited historical seasons |

## Development

```bash
cd mcp/datahub
npm install
npm run dev          # Run with tsx (hot reload)
npm test             # Run tests
npm run build        # Build for production
```