media-mcp

Media Metadata MCP Server

An MCP (Model Context Protocol) server that enriches book, movie, and TV show metadata for Obsidian vaults. Queries multiple sources, normalizes data, and returns Obsidian-ready frontmatter.

Features

• Book Lookup: Search by title, author, or ISBN via Open Library
• Movie Lookup: Comprehensive movie data from TMDB including cast, directors, collections, and watch providers
• TV Show Lookup: Full TV show metadata including seasons, episodes, and networks
• Frontmatter Generation: Convert lookup results to Obsidian YAML frontmatter
• Batch Processing: Look up multiple items in a single request
• Caching: SQLite-based caching with configurable TTLs
• Multiple Transports: Support for both stdio and Streamable HTTP transports

Installation

npm install
npm run build

Configuration

The server is configured via environment variables. App-specific variables use the MCP_ prefix; standard API/telemetry variables use their conventional names.

API Keys

Variable	Description	Default
TMDB_API_KEY	TMDB API key (required for movie/TV lookups)	-
GOOGLE_BOOKS_API_KEY	Google Books API key (optional, for enhanced book data)	-

Transport

Variable	Description	Default
MCP_TRANSPORT	Transport type: stdio or http	stdio
MCP_HTTP_PORT	HTTP server port	3000
MCP_HTTP_HOST	HTTP server host	127.0.0.1
MCP_HTTP_PATH	HTTP endpoint path	/mcp

Cache

Variable	Description	Default
MCP_CACHE_ENABLED	Enable caching	true
MCP_CACHE_PATH	SQLite cache database path	./cache.db
MCP_CACHE_TTL_BOOKS	Book cache TTL in seconds	604800 (7 days)
MCP_CACHE_TTL_MOVIES	Movie cache TTL in seconds	86400 (1 day)
MCP_CACHE_TTL_TV	TV cache TTL in seconds	86400 (1 day)

Rate Limiting

Variable	Description	Default
MCP_RATE_LIMIT_RPM	Requests per minute	30
MCP_RATE_LIMIT_RETRIES	Retry attempts	3

Features

Variable	Description	Default
MCP_ENABLE_GOODREADS_SCRAPING	Enable Goodreads scraping	true
MCP_ENABLE_COVER_DOWNLOAD	Enable cover image download	false
MCP_COVER_DOWNLOAD_DIR	Cover download directory	./covers

Logging

Variable	Description	Default
MCP_LOG_LEVEL	Log level: debug, info, warn, error	info

OpenTelemetry

Variable	Description	Default
OTEL_ENABLED	Enable OpenTelemetry	false
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry endpoint URL	-
OTEL_SERVICE_NAME	Service name	media-metadata-mcp

Getting API Keys

TMDB API Key (Required for Movie/TV)

1. Create a free account at TMDB
2. Go to Settings → API
3. Request an API key (choose "Developer" option)
4. Copy your API Read Access Token

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "media-metadata": {
      "command": "node",
      "args": ["/path/to/media-metadata-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "your-tmdb-api-key"
      }
    }
  }
}

With Claude Code

{
  "mcpServers": {
    "media-metadata": {
      "command": "node",
      "args": ["/path/to/media-metadata-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "your-tmdb-api-key"
      }
    }
  }
}

HTTP Transport

Start the server with HTTP transport:

TMDB_API_KEY=your-key MCP_TRANSPORT=http npm start

Or:

TMDB_API_KEY=your-key node dist/index.js --transport http

Connect your MCP client to http://127.0.0.1:3000/mcp

Tools

lookup_book

Look up book metadata by title, author, or ISBN.

Input:

{
  "title": "The Name of the Wind",
  "author": "Patrick Rothfuss",
  "isbn": "978-0756404741"
}

Output: Book metadata including title, authors, ISBN, genres, page count, description, cover URL, series information, and ratings.

lookup_movie

Look up movie metadata by title and optional year.

Input:

{
  "title": "Inception",
  "year": 2010
}

Output: Movie metadata including title, year, runtime, genres, description, cast, director, collection info, ratings, and watch providers.

lookup_tv

Look up TV show metadata by title.

Input:

{
  "title": "Breaking Bad",
  "include_seasons": true,
  "include_episodes": false
}

Output: TV show metadata including title, status, genres, seasons, episodes, networks, and ratings.

generate_frontmatter

Convert a lookup result to Obsidian YAML frontmatter.