Uses .ENV for configuration management, allowing users to set database credentials and connection parameters
Installation process uses Git for cloning the repository
Built for Node.js runtime (v18 or higher), with the server executing as a Node.js application
Uses npm for package management and running server commands
Uses PostgreSQL as the database backend, leveraging its JSONB support for flexible storage of video metadata with advanced querying capabilities
Implemented in TypeScript with type definitions for video metadata and database schema
Supports Yarn as an alternative package manager for installation
Implements validation schemas using Zod for parameter validation and error handling
Video Metadata MCP Server
A Model Context Protocol (MCP) server for managing video metadata with game information, teams, scores, and other sports-related data. This server uses PostgreSQL as the database backend.
Features
- CRUD Operations: Create, read, update, and delete video metadata records
- Advanced Search: Filter videos by game type, teams, league, season, tags, and date ranges
- PostgreSQL Integration: Robust database with JSONB support for flexible data storage
- MCP Protocol: Compatible with Claude Desktop and other MCP clients
- Rich Metadata: Support for game statistics, player data, venues, and more
Database Schema
The server manages video metadata with the following fields:
id
: Unique identifier (auto-generated)title
: Video titlegame_type
: Type of game (e.g., "basketball", "football", "soccer")teams
: Array of participating team namesscore
: Final score as a stringduration_seconds
: Video duration in secondsvideo_url
: URL to the video filethumbnail_url
: URL to the thumbnail imagedescription
: Video descriptiontags
: Array of tags for categorizationplayer_stats
: JSON object containing player statisticsmatch_date
: Date when the match was playedvenue
: Location where the match took placeleague
: League or competition nameseason
: Season identifiercreated_at
/updated_at
: Timestamps
Prerequisites
- Node.js (v18 or higher)
- PostgreSQL (v12 or higher)
- npm or yarn
Installation
- Clone and setup the project:
- Configure PostgreSQL:
- Ensure PostgreSQL is running
- Create a database named
video_metadata
(or use your preferred name) - Copy
.env.example
to.env
and update the database credentials:
- Update environment variables in
.env
: - Build the project:
- Initialize the database with sample data:
Usage
Running the MCP Server
The server will run on stdio and can be connected to by MCP clients.
Available Tools
The server provides the following tools:
1. list_video_metadata
Get all video metadata records.
2. get_video_metadata
Get a specific video metadata record by ID.
- Parameters:
id
(number)
3. search_video_metadata
Search video metadata with filters.
- Parameters:
game_type
(string, optional)teams
(array of strings, optional)league
(string, optional)season
(string, optional)tags
(array of strings, optional)match_date_from
(ISO date string, optional)match_date_to
(ISO date string, optional)
4. create_video_metadata
Create a new video metadata record.
- Required Parameters:
title
,game_type
,teams
- Optional Parameters: All other fields
5. update_video_metadata
Update an existing video metadata record.
- Required Parameters:
id
- Optional Parameters: Any field to update
6. delete_video_metadata
Delete a video metadata record.
- Parameters:
id
(number)
7. get_game_types
Get all unique game types from the database.
8. get_teams
Get all unique teams from the database.
9. get_leagues
Get all unique leagues from the database.
Example Usage with Claude Desktop
Add this to your Claude Desktop MCP configuration:
Sample Data
The setup script includes sample data for:
- NBA Finals Game 7 (Lakers vs Celtics)
- Super Bowl LVIII (Chiefs vs 49ers)
- Champions League Final (Real Madrid vs Liverpool)
Development
Project Structure
Building
Adding New Features
- Extend the
VideoMetadata
interface indatabase.ts
- Add corresponding database schema changes in
initializeSchema()
- Implement new tools in the MCP server (
index.ts
) - Add validation schemas using Zod
Database Indexes
The following indexes are automatically created for optimal performance:
idx_video_metadata_game_type
: On game_type fieldidx_video_metadata_teams
: GIN index on teams JSONB arrayidx_video_metadata_tags
: GIN index on tags JSONB arrayidx_video_metadata_match_date
: On match_date fieldidx_video_metadata_league
: On league field
Error Handling
The server includes comprehensive error handling:
- Database connection errors
- Invalid parameter validation (using Zod schemas)
- Resource not found errors
- Proper MCP error codes and messages
Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request
License
MIT License - see LICENSE file for details.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Manages sports video metadata with CRUD operations for game information, teams, scores, and statistics. Enables advanced search filtering by game type, teams, league, season, and date ranges through PostgreSQL integration.
Related MCP Servers
- -securityFlicense-qualityProvides programmatic access to comprehensive football statistics and live match data via API-Football, enabling applications to retrieve league standings, team fixtures, player statistics, and real-time match events.Last updated -Python
- -securityFlicense-qualityProvides structured access to NHL data including teams, players, standings, schedules, and statistics through the Model-Context Protocol pattern.Last updated -TypeScript
- -securityAlicense-qualityA Modular Command-line Program for fetching and filtering NFL transaction data, including player movements, injuries, disciplinary actions, and more from ProSportsTransactions.com.Last updated -PythonMIT License
- -securityFlicense-qualityAn MCP server that enables interaction with MLB (Major League Baseball) v3 projections through the SportsData.io API, allowing access to baseball statistics and projections through natural language.Last updated -Python