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 credential for movie/TV lookups — accepts either a v3 API Key (32-hex) or a v4 Read Access Token; the server auto-detects the scheme	-
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 and request a key (choose the "Developer" option)
3. That page exposes two credentials — either one works:
   • API Key (v3 auth) — a 32-character hex string, sent as the api_key query parameter
   • API Read Access Token (v4 auth) — a longer JWT, sent as an Authorization: Bearer header
4. Copy either one into TMDB_API_KEY. The server auto-detects the scheme from the value's shape — do not prepend Bearer .

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.