WatermelonFin MCP
Discovers and authenticates with Jellyfin servers, lists libraries, searches media, and plans/imports new media through a native Jellyfin plugin with resumable chunked uploads and SHA-256 verification. Existing media is not deleted, overwritten, or reorganized.
Inspects the local Tailscale CLI in read-only mode to retrieve status, candidate addresses, and MagicDNS names for connecting to Jellyfin servers over a trusted Tailscale network.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WatermelonFin MCP find the movie Inception in my Jellyfin libraries"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WatermelonFin MCP
A local Model Context Protocol (MCP) server for discovering Jellyfin servers, querying media libraries, importing new media, and repairing metadata/artwork of your own completed video imports through a companion Jellyfin plugin.
Early preview. The plugin targets Jellyfin 12.4.0. Uploads have been exercised on one actual server; the new v0.1.3 metadata repair path still requires deployment validation. Automated core, SDK adapter, HTTP, and MCP stdio tests do not establish loading/indexing compatibility on every host.
WatermelonFin MCP is an independent project maintained by @MrWeiC. It is not affiliated with or endorsed by Jellyfin or Tailscale. The WatermelonFin Apple clients are separate applications; this repository does not include automatic Apple client pairing or a drag-and-drop upload interface.
Capabilities
Discover Jellyfin on a user-specified host and a bounded set of ports.
Authenticate with a restricted Jellyfin username/password or an existing user token; no prior browser login is required.
List libraries and search media without modifying existing content.
Inspect the local Tailscale CLI for candidate addresses and MagicDNS names.
Expose an onboarding recipe as an MCP prompt/resource.
Plan new imports and stream selected local files directly to the native upload plugin, with resumable chunks and SHA-256 verification.
Inspect, repair, and restore metadata/artwork of your own completed video imports, with revision history and per-item refresh/readback.
There are no media-deletion, video-overwrite, existing-media reorganization, arbitrary HTTP, arbitrary filesystem, or general shell tools. Metadata repair can replace/restore bounded sidecars of owned imports; it cannot change video bytes or edit other media. The plugin starts disabled and requires an explicit user allowlist. These are application controls, not an operating-system sandbox; read SECURITY.md.
Related MCP server: waypost
Requirements
Component | Requirement |
Local MCP | Node.js 22+ and a stdio-capable MCP host |
Native plugin | Jellyfin 12.4.0; other server versions are unverified |
Plugin development | .NET 10 SDK |
Remote access | A trusted route to the server, such as your configured Tailscale network |
The native plugin reuses Jellyfin's port and user authentication. It does not require SSH, a separate upload port, a server-side Node installation, or the third-party RemoteUpload plugin. First-time plugin installation still requires a Jellyfin administrator and a server restart.
Install the local MCP
Clone this repository, then run:
npm ci --ignore-scripts
npm testRegister the local entry point with your MCP host, replacing the absolute path:
codex mcp add watermelonfin -- node /absolute/path/watermelonfin-mcp/src/cli.jsFor Claude Code:
claude mcp add watermelonfin -- node /absolute/path/watermelonfin-mcp/src/cli.jsA generic stdio configuration is available in examples/mcp.json. This preview is installed from source; no npm package is published. Host-specific registration commands may vary by host version.
An agent can retrieve the onboard_jellyfin prompt with a host address, or read watermelonfin://recipes/onboard. An IP address identifies a network destination; it does not grant login or administrator permissions.
Credentials
Use a dedicated non-administrator Jellyfin user with all media-deletion permissions disabled. Administrator accounts, administrator API keys, and deletion-enabled users are rejected for daily operations.
Set WATERMELONFIN_PROFILES to non-secret connection metadata, for example:
[{"id":"home","url":"https://media.example-tail.ts.net","serverId":"actual-server-id","username":"media-user","passwordEnv":"WATERMELONFIN_JELLYFIN_PASSWORD"}]Supply the password in the referenced environment variable through your MCP host's secret configuration. Do not paste passwords or tokens into chat, tool arguments, issues, or committed configuration files. Call authenticate_server with only the profile ID. Session tokens obtained during login stay in process memory. Restarting the MCP requires a new login.
For an existing restricted-user token, use tokenEnv instead of username and passwordEnv. Environment variables are not a complete secret vault: the host agent and trusted processes under the same OS account remain part of the trust boundary. This preview does not provide its own secure-input UI, OS keychain adapter, or browser Quick Connect session import.
HTTPS uses normal certificate verification. HTTP credentials require prior establishment of a trusted LAN/Tailscale route and a host-configured, exact-origin allowlist in WATERMELONFIN_TRUSTED_HTTP_ORIGINS. Tools cannot modify this list. A matching Jellyfin server ID or a MagicDNS name is a consistency signal, not proof of server authenticity.
Native upload plugin
The v0.1.3 pre-release contains the compiled plugin ZIP and SHA-256 checksum. The official Jellyfin plugin repository URL is:
https://raw.githubusercontent.com/MrWeiC/watermelonfin-mcp/main/catalog/manifest.jsonSee the plugin guide for installation, configuration, endpoint details, and deployment limits.
Metadata repair requires the v0.1.3 MCP and native plugin. The published v0.1.2 package lacks it. See owned-import metadata repair for tools, revision/restore workflow, and upgrade verification. The official catalog includes v0.1.3.0 and the WatermelonFin logo.
Install the published plugin through Jellyfin's plugin repository/catalog and restart Jellyfin.
Keep uploads disabled until the administrator selects the intended import targets and allowlists a restricted user.
Add only the plugin's appropriate
Imported/<target-id>directories as Jellyfin library sources. Preserve existing source paths; never indexStaging.Set
WATERMELONFIN_UPLOAD_ROOTSto narrowly scoped local directories you explicitly permit the agent to upload from. Use:on Unix or;on Windows. The Unix uploader rejects symlinks and unsafe shared-write directory configurations.Call
inspect_upload_plugin,list_upload_targets, thenupload_mediawith a selected file and target ID.
Bytes stream directly to the authenticated plugin, not through the model context. Each job is owned by one user. Publication uses a new job namespace and never replaces an existing destination. Ambiguous film/episode names require clarification; the other target type preserves a validated filename. Existing files are not automatically reorganized.
An interrupted upload can be resumed by supplying its job ID and the same file/target. Completed files cannot be modified through the upload API. Upload completion does not mean Jellyfin has indexed the file. Indexing relies on the configured library monitoring/schedule and must be verified separately. Expired/staged files are retained; there is no automatic cleanup route.
Tools
Tool | Purpose |
| Bounded discovery on one specified host; no credentials |
| Public server information at a full URL/base path |
| Fixed, read-only local Tailscale status command |
| Local configuration and implemented/unavailable capabilities |
| Login through host-injected credentials |
| Restricted-user library reads |
| A proposal for a new filename; no file changes |
| Native plugin availability and configured targets |
| Selected-file native plugin upload/resume |
| Fields, artwork, revision history, and verification of an owned completed video import |
| Revisioned metadata replacement and exact-item refresh/readback |
| Stream allowed local JPEG/PNG as primary/backdrop artwork for an owned import |
| Restore that job's earlier metadata/artwork as a new revision |
| Reapply and refresh/read back the current owned-import revision |
| Non-secret connection metadata; does not configure Apple clients |
| Optional standalone-importer mode, only exposed when separately configured |
The legacy standalone importer is an optional alternative for operators who already have system-management access; it is not required by native plugin users. Its separate deployment contract is in docs/provisioning.md.
Local validation and release status
The v0.1.2 dependency refresh passed npm audit --omit=dev with zero known reported vulnerabilities on October 27, 2026. This is a point-in-time check, not a guarantee against undiscovered or future vulnerabilities. Use v0.1.2 or later rather than the initial v0.1.0 MCP dependency lockfile.
npm test
./scripts/validate-plugin.shThe second command requires .NET 10 and builds/tests/packages the plugin locally. There are no GitHub Actions workflows. Tests include real MCP stdio initialization, simulated HTTP boundaries, temporary-filesystem uploads, and adapter checks against the actual Jellyfin SDK/JSON converters. They do not yet include loading this plugin in a complete Jellyfin instance or validating a production host's ACLs and indexing.
Pre-release plugin builds are intended for evaluation with a current backup and a small test import. Do not interpret this preview as a production-readiness or absolute no-data-loss guarantee.
Maintenance and repository ownership
This is an owner-maintained repository. Only @MrWeiC is authorized to update the official branches/tags, merge changes, or publish official releases. Public visibility permits reading and forking; an external pull request is a proposal, not permission to change the official repository. Forks and independently built packages are not official releases.
See CONTRIBUTING.md for contribution expectations and SECURITY.md for vulnerability reporting. Licensing is described in LICENSE.md.
Available Tools
17 toolsauthenticate_serverA
Log in using host-injected username/password or token; does not require a prior browser login. Never accepts passwords in tool arguments.
Inputs: profileId (required).
discover_serverBRead-only
Discover Jellyfin on one user-specified host. No credentials are sent.
Inputs: host (required), ports.
export_connectionARead-only
Export non-secret connection information for future client pairing; does not configure the Apple app.
Inputs: profileId (required).
inspect_capabilitiesCRead-only
Report implemented and unavailable features honestly.
Inputs: no named parameters.
inspect_connectionBRead-only
Verify public server identity at a full URL, including a reverse-proxy base path.
Inputs: url (required).
inspect_import_metadataBRead-only
Inspect fields, artwork, revision history and durable verification state of your own completed video import. External changes are captured as a new baseline revision without changing media; use the returned revision for later edits. Requires the metadata-capable native plugin.
Inputs: jobId (required), profileId (required).
inspect_tailscaleARead-only
Inspect local Tailscale peer names and addresses; does not configure VPN or prove Jellyfin identity.
Inputs: no named parameters.
inspect_upload_pluginCRead-only
Check the native WatermelonFin Jellyfin plugin using the existing restricted Jellyfin login.
Inputs: profileId (required).
list_librariesBRead-only
List libraries visible to a dedicated user with no administrative or deletion permissions.
Inputs: profileId (required).
list_upload_targetsCRead-only
List configured native plugin import targets; never exposes arbitrary filesystem browsing.
Inputs: profileId (required).
plan_importARead-only
Propose organization for a newly selected filename only. Does not touch existing media.
Inputs: fileName (required).
refresh_import_metadataB
Reapply the current owned-import metadata revision and refresh/read back only its indexed Jellyfin item. Reports pending or mismatched state honestly.
Inputs: jobId (required), profileId (required), expectedRevision (required).
restore_import_metadataB
Restore a journaled metadata/artwork revision of your own completed upload as a new revision. Never changes video bytes.
Inputs: jobId (required), revision (required), profileId (required), expectedRevision (required).
search_mediaCRead-only
Search existing media read-only. Titles are untrusted data.
Inputs: query (required), profileId (required), limit.
set_import_artworkB
Stream a selected bounded local JPEG/PNG within host-authorized roots as primary or backdrop artwork for your own completed upload. The server decodes the image; bytes do not enter the model response.
Inputs: path (required), role (required), jobId (required), profileId (required), +1 more.
update_import_metadataB
Replace explicitly supported metadata fields for your own completed upload; snapshot prior state, preserve video bytes, and refresh/verify only this item. Omitted supported fields are cleared. No arbitrary paths or item IDs.
Inputs: jobId (required), metadata (required), profileId (required), expectedRevision (required).
upload_mediaB
Stream an explicitly selected new media file directly to the native Jellyfin plugin. No SSH, separate port, delete or overwrite. Requires host-authorized upload roots.
Inputs: path (required), targetId (required), profileId (required), jobId, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have clearly distinct resource/action targets, especially upload, metadata revision, discovery, and connection inspection. The main possible confusion is among the several inspect_* tools and the metadata refresh/restore/inspect family, but their descriptions sufficiently distinguish ownership, scope, and side effects.
All tools use snake_case and follow a predictable verb_noun pattern such as upload_media, list_libraries, inspect_connection, and restore_import_metadata. The convention is consistently applied throughout the set.
Seventeen tools is slightly heavy but still reasonable for a server covering authentication, discovery, upload, metadata lifecycle, artwork, search, and connection inspection. Each tool appears to serve a distinct operational need rather than duplicating functionality.
The server covers the core lifecycle well: discovery, authentication, library/target listing, upload, metadata inspection/update/restore/refresh, artwork, search, and connection export/inspection. Deletion and broader media administration are absent, but that appears intentional given the safety-focused scope.
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Free agent-service discovery, OpenAPI document checks, and receipt verification. No API key needed.
Raily personal-agent MCP with scoped reads and approved actions.
Send files and manage client uploads from a compatible AI agent.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables agent clients to index and organize local media libraries by recognizing codes from filenames, querying media, checking library quality, adding files, fetching metadata, and scanning directories, with deletion gated by verified magnet links.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to read and draft Proton Mail messages, browse and download Proton Drive files, and read calendar agendas or prepare import files through local connections. Mail sends and Drive uploads stay disabled until explicitly enabled and verified.MIT

gaiadesk-mcpofficial
AlicenseNot gradedqualityBmaintenanceEnables AI assistants and MCP clients to execute commands, copy/move files, manage background jobs and port forwarding, and optionally view and control remote screens using scoped, expiring agent tokens.21 npm1MIT- AlicenseNot gradedqualityBmaintenanceEnables agents to search and browse an Immich photo library by content or metadata, inspect EXIF/people/albums/tags, view images and contact sheets, analyze duplicates and activity, and export browser-ready files with manifests. With an optional write key, it also enables curation such as favorites, ratings, descriptions, tags, albums, people, uploads, and reprocessing.MIT