FolioSpace Library

MCP

Install the local MCP bridge for agents.

FolioSpace Library MCP runs on the machine where your AI Agent is running. It connects to the FolioSpace Library service on your NAS through a secure Bearer Token.

MCP does not need to be deployed on the same device as FolioSpace Library. It handles control and lookup for directories, works, games, scans, status, and play records. Media files are still accessed through authenticated URLs returned by the server, so real NAS paths are not exposed to clients.

MCP 1.04: search, stored diagnostics and metadata review

71 tools are available, including nine additions for Library 1.11. The bridge checks server capabilities; older servers return capability-unsupported for these additions.

foliospace.list_books
foliospace.browse_comics
foliospace.search_library
foliospace.diagnose_book
foliospace.diagnose_game
foliospace.search_video_metadata
foliospace.get_video_metadata_job
foliospace.preview_video_metadata
foliospace.apply_video_metadata

Page through books with format filters, browse comic folders, and search books, games and videos together. Cross-media cursors exclude later insertions but are not database snapshots; edits or deletions can change subsequent matches.

Book and game diagnostics report stored evidence without opening media, scanning, repairing or updating health. They do not establish current filesystem availability.

For one video, explicitly request a candidate search from the configured TMDB provider, inspect a candidate preview, then apply that exact preview with confirm: true. Search contacts the provider and writes a job. Preview leaves persisted media unchanged and issues a ten-minute in-memory receipt. Apply revalidates the receipt and target; expired, stale or reused receipts fail. Manual overrides are preserved. This is not automatic bulk editing.

Use a valid bearer token and explicit profile context for metadata operations. Profiles separate personal state; a profile ID is not a user access-control boundary.

The existing 62 tools, including movie works, seasons, episodes, versions, availability and playback-state lookup, remain available.

The installer verifies checksums and initialization, preserves your URL/token configuration, and keeps one previous binary. Reconnect Hermes or your other MCP host after upgrading. MCP uses stdio; media bytes still use authenticated HTTP URLs.

Official MCP 1.04 release · Workflow contract · Usage and Hermes configuration

Install

curl -fsSL https://foliospace.app/install-mcp.sh | sh

This installs the separately versioned MCP 1.04 bridge to ~/.local/bin/foliospace-mcp from the canonical GitHub mcp-v1.04 release. Identical packages are also mirrored under this website's /releases path.

Client configuration

{
  "mcpServers": {
    "foliospace-library": {
      "command": "/Users/you/.local/bin/foliospace-mcp",
      "env": {
        "FOLIOSPACE_BASE_URL": "http://your-nas-ip:8080",
        "FOLIOSPACE_API_TOKEN": "your-access-key"
      }
    }
  }
}

What MCP is for

Use MCP for lookup, diagnostics, manifests, preferences, private state, progress, scan jobs, scan settings, and error summaries. MCP does not transfer large files. Comic pages, EPUB resources, PDF content, ROM files, video streams, HLS playlists, and thumbnails are still read through URLs returned by the HTTP Client API.

Because the MCP server talks to your own FolioSpace Library instance, it needs FOLIOSPACE_BASE_URL and, when auth is enabled, FOLIOSPACE_API_TOKEN.

Common tools

Dynamic game-platform discovery

MCP 1.04 includes foliospace.get_game_platform_catalog. It returns every platform recognized by the connected FolioSpace Library server, including stable IDs, display titles, aliases, indexed counts, and availability. Agents should use it when generating platform menus or answering which systems the server supports.

foliospace.list_game_platforms remains the inventory-only facets tool for platforms currently represented by visible game records.

Resources