Video Metadata

You run a Video Metadata MCP Server to manage game-specific video metadata, including teams, scores, venues, and player statistics, with PostgreSQL as the backend. It exposes a set of MCP tools for creating, retrieving, updating, and listing video metadata, and it works with MCP clients to power search, filters, and rich metadata handling for sports videos.

How to use

Connect to the Video Metadata MCP Server with your MCP client. You can perform common tasks such as listing all records, retrieving a single record by ID, searching with filters (game type, teams, league, season, tags, and date ranges), and creating or updating records. Use the provided tools to manage exercise-ready metadata for sports videos, including storing game statistics, venues, and match dates. The server runs over stdio in a local process, so you typically start it as a background or foreground service and connect your MCP client to its standard input/output streams.

How to install

Prerequisites you need before installing this MCP server are Node.js version 18 or higher and PostgreSQL version 12 or higher. You also need npm or yarn as your package manager.

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

# 2) Configure PostgreSQL (example values shown; replace with real credentials)
# Ensure PostgreSQL is running and a database is available
cp .env.example .env

# 3) Update environment variables in .env
# Replace placeholders with your actual credentials
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=video_metadata

# 4) Build the project
npm run build

# 5) Initialize the database with sample data (optional)
npm run setup

# 6) Start the MCP server
npm start

Additional sections

Configuration, security, and troubleshooting notes follow to help you operate the server confidently. The server uses PostgreSQL JSONB fields for flexible data storage and exposes a set of MCP tools to manage video metadata. Make sure PostgreSQL is reachable from the server host and that the database name matches your .env configuration. If you encounter connection errors, verify that POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB are correct and that the database is accessible from your network. When updating schemas or adding new features, extend the VideoMetadata interface and corresponding database initialization accordingly, and ensure Zod-based validation remains in place for parameter safety.

MCP client configuration example

{
  "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"
      }
    }
  }
}

Available tools

list_video_metadata

Retrieve all video metadata records from the database.

get_video_metadata

Fetch a single video metadata record by its ID.

search_video_metadata

Query records using filters such as game_type, teams, league, season, tags, and match date range.

create_video_metadata

Create a new video metadata record with required fields and optional metadata.

update_video_metadata

Modify an existing video metadata record by ID, updating any allowed fields.

delete_video_metadata

Remove a video metadata record by ID.

get_game_types

List all unique game types present in the database.

get_teams

List all unique teams stored in metadata.

get_leagues

List all unique leagues stored in metadata.