Video Metadata

You can manage rich video metadata for games, teams, scores, and related data using a PostgreSQL-backed MCP server. It provides CRUD operations, advanced search, and seamless integration with MCP clients to power game-focused applications and analytics.

How to use

Connect to the Video Metadata MCP Server with your MCP client. The server exposes a set of tools you can call to list, retrieve, search, create, update, and delete video metadata records. You can search by game type, teams, league, season, tags, and date ranges to locate exactly the records you need. You can also retrieve aggregated lists such as all game types, teams, or leagues to help build filters in your client.

To work with the server, start the local MCP process and connect your client to the runtime. The server runs in stdio mode when you launch it locally, which makes it easy to run alongside your development environment. Ensure your client is configured to talk to the MCP server using the correct command path and environment variables as shown in the runtime example.

How to install

# 1) Clone the project
git clone <repository-url>
cd metadata-mcp

# 2) Install dependencies
npm install

# 3) Configure PostgreSQL
# Ensure PostgreSQL is running and create a database named video_metadata (or use your own name)

# 4) Prepare environment configuration
cp .env.example .env
# Update database credentials in .env:
# POSTGRES_USER=your_username
# POSTGRES_PASSWORD=your_password
# POSTGRES_HOST=localhost
# POSTGRES_PORT=5432
# POSTGRES_DB=video_metadata

# 5) Build the project
npm run build

# 6) Initialize the database with sample data
npm run setup

# 7) Start the MCP server
npm start

Additional content

Configuration notes: The MCP server uses PostgreSQL as its backend and includes a set of tools to operate on video metadata records. The server supports environmental configuration for database access and runs the MCP process in stdio mode for local development. You can customize the database connection by editing the .env file with your credentials and host information.

Security and maintenance tips: Keep PostgreSQL accessible only from trusted hosts, rotate database credentials periodically, and monitor the MCP server logs for validation errors or resource issues. When deploying, consider separating the MCP process from client-facing services and use proper access controls for your client applications.

Example MCP client configuration for local runtime: you can connect your MCP client to the local server using the following local runtime setup. This only covers the local stdio approach and shows how the server can be launched within your development environment.

{
  "mcpServers": {
    "video_metadata": {
      "command": "node",
      "args": ["/path/to/metadata-mcp/build/index.js"],
      "env": {
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "video_metadata"
      }
    }
  }
}

API surface and available actions

The server exposes a collection of tools to manage video metadata records:

• list_video_metadata — Get all video metadata records
• get_video_metadata — Get a specific video metadata record by ID
• search_video_metadata — Search video metadata with filters (game_type, teams, league, season, tags, and date ranges)
• create_video_metadata — Create a new video metadata record (title, game_type, teams are required)
• update_video_metadata — Update an existing video metadata record (specify id)
• delete_video_metadata — Delete a video metadata record by ID
• get_game_types — Retrieve all unique game types
• get_teams — Retrieve all unique teams
• get_leagues — Retrieve all unique leagues

Notes on data model and indexes

The video metadata records include fields such as title, game_type, teams, score, duration, URLs for the video and thumbnail, description, tags, player_stats, match_date, venue, league, season, and timestamps. Indexes are created to optimize queries on game_type, teams (JSONB array), tags (JSONB array), match_date, and league.

Available tools

list_video_metadata

Retrieve all video metadata records in the database.

get_video_metadata

Fetch a single video metadata record by its ID.

search_video_metadata

Query video metadata using filters like game_type, teams, league, season, tags, and date range.

create_video_metadata

Create a new video metadata record with required fields such as title, game_type, and teams.

update_video_metadata

Update fields of an existing video metadata record identified by ID.

delete_video_metadata

Remove a video metadata record by its ID.

get_game_types

Return all distinct game types present in the dataset.

get_teams

Return all distinct teams present in the dataset.

get_leagues

Return all distinct leagues present in the dataset.