simkl-mcp
Allows reading and managing a user's Simkl watch history, library, and ratings, including searching titles, resolving external IDs, logging watched items, updating statuses, and rating titles.
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., "@simkl-mcp What have I watched recently?"
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.
simkl-mcp
An MCP server wrapping the Simkl API, so Claude can read your watch history and log what you've watched.
This is the only place a Simkl token lives. re-com-video
— the recommendation engine — is read-only and calls these tools rather than holding a
credential itself, so a recommender can never be the thing that also mutated the history it
claims to have excluded.
Tools
Reading
Tool | Does |
| Whether a usable token is stored. Never returns the token. |
| Timestamps of the user's most recent list changes. The cheapest call in the API, and the gate for every sync. |
| Watch history and watchlists, normalized. With |
| Every Simkl ID and nothing else — the cheap half of deletion reconciliation. |
| Ask Simkl directly whether specific titles are already in the library. |
| The titles the user rated themselves. |
| Full detail record, including |
| External ID → Simkl ID. |
| Search by title. Use |
Writing
Tool | Does |
| Record watch events. |
| Move titles to |
| Rate 1–10. |
| Remove from history. Also clears the item's rating. |
| Delete the local token. |
Related MCP server: Fathom AI MCP Server
Setup
python3 -m venv .venv && source .venv/bin/activate
pip install -e .Register a free app at simkl.com/settings/developer. The
PIN flow needs no client_secret and no redirect URI, so the redirect URI field can be anything
(urn:ietf:wg:oauth:2.0:oob is conventional).
python scripts/setup_auth.py --client-id YOUR_CLIENT_IDIt prints a five-character code; enter it at simkl.com/pin. The token is
written to simkl_auth.json (mode 600, gitignored). Simkl issues no refresh token — the
token lasts about five years, and a 401 means the app was revoked at
simkl.com/settings/apps.
Register as an MCP server:
{
"mcpServers": {
"simkl": {
"command": "/path/to/simkl-mcp/.venv/bin/python",
"args": ["/path/to/simkl-mcp/server.py"],
"env": { "SIMKL_AUTH_PATH": "/path/to/simkl-mcp/simkl_auth.json" }
}
}
}Tests
pip install -e ".[dev]" && python -m pytest tests -qNo network and no token required — every HTTP call is faked.
What this server is careful about
Simkl's API has a handful of behaviours that fail quietly, which is the class of bug this project is built to avoid. Each is handled here and has a test:
Anime entries nest under
show, notanime. Reading the wrong key silently returns an empty anime library — and an exclusion gap nothing would notice.Browse filters silently widen. An unrecognised
typeorstatussegment is treated as "all" and still returns200. This server rejects unknown filter values instead of sending them.Movies have no
watchingorholdstatus. Refused up front rather than silently ignored.TMDB IDs are not unique across movie and TV.
resolve_idrefuses a TMDB ID without a type.Slugs are not unique (three different Superman films share one), so links are built from the Simkl ID.
/redirectmust not be followed. TheLocationheader is the whole answer; the destination is HTML.The PIN
device_codeis the literal string"DEVICE_CODE"— a placeholder. Polling usesuser_code, and stops at the first token (Simkl deletes an approved code, and polling an unknown one falls through to issuing a new code).Deltas never contain deletions.
get_library(date_from=…)says so in its response.History rows with no Simkl ID are counted, not dropped.
skipped_without_simkl_idis part of every library response.
Simkl's terms
Free for non-commercial and personal projects. Every request sends client_id, app-name,
app-version and a User-Agent, as required, and every title this server returns carries a link
back to its Simkl page. See api.simkl.org/api-rules.
License
MIT
Available Tools
14 toolsget_activitiesA
Timestamps of the user's most recent list changes.
The cheapest call in the API and the gate for every sync: if all has not
moved since the last recorded value, nothing needs fetching.
Inputs: no named parameters. Returns: object
get_libraryA
Read the watch history and watchlists.
type: shows, movies or anime. Omit for all three in one call. status: watching, plantowatch, hold, completed or dropped. Omit for all. date_from: an ISO timestamp from get_activities, passed back byte-for-byte. With it you get only what changed since; without it, the full library.
Deletions never appear in a delta. When activities' removed_from_list
moves, call get_library_ids and diff instead.
Returns normalized items plus skipped, the number of entries that carried
no Simkl ID. A non-zero skipped is a hole in the exclusion guarantee and
must be reported to the user, not hidden.
Inputs: type, status, date_from. Returns: object
get_library_idsA
Every Simkl ID in the library, and nothing else.
The cheap half of deletion reconciliation: IDs present locally but absent here have been removed from Simkl, and any rating stored for them is gone too (Simkl wipes the rating on removal).
Inputs: type. Returns: object
get_ratingsA
The titles the user has rated themselves.
type: movies, shows or anime. rating: 1-10, or omit for every rating. Ratings 8-10 are the strong positive seeds for "what should I watch tonight"; 1-4 are the negative signal (PLAN.md 5.1).
Inputs: type (required), rating. Returns: object
get_titleA
Full detail record for one title, including its viewer-based neighbours.
type: movie, tv or anime -- Simkl's own classification, which can change for a given title; follow it rather than assuming.
The record carries users_recommendations: titles suggested from what this
title's viewers also watched. That is the viewer signal re-com-video ranks
on, and the count varies enormously by title.
Inputs: type (required), simkl_id (required). Returns: object
login_statusA
Whether this server holds a usable Simkl token, without revealing it.
Inputs: no named parameters. Returns: object
logoutA
Delete the stored Simkl token from this machine.
This does not revoke the app on Simkl's side -- do that at simkl.com/settings/apps.
Inputs: no named parameters. Returns: result
lookup_watchedA
Ask Simkl directly whether specific titles are already in the library.
items: a list like [{"simkl": 54130}, {"imdb": "tt0110912"}] -- any mix of supported ID keys. Simkl returns a parallel array with each item's library status and last-watched time.
This is the server-side check behind re-com-video's "never already seen" guarantee. It is independent of the local mirror, so it catches anything watched since the last sync.
Inputs: items (required). Returns: result
mark_watchedA
Record that the user watched these titles.
items: [{"ids": {"simkl": 54130}}, ...]. Add "watched_at" (ISO, UTC) if the date is known; omit it for "now". For "a long time ago, don't remember", Simkl's placeholder is 1970-01-01T00:00:01Z -- store that, and never display it as a literal 1970 date.
type: movie, tv or anime. Anime goes in the shows[] envelope.
Simkl serialises sync writes per user behind a 20-second lock, so batch rather than sending one call per title.
Inputs: type (required), items (required). Returns: object
rateB
Rate titles 1-10.
Rating something that is on no list auto-files it: a released movie becomes completed, an unreleased one plan-to-watch, a single-episode show completed, anything else watching. That move is intended -- read the next delta as authoritative rather than trying to predict it.
Inputs: type (required), items (required), rating (required). Returns: object
remove_from_historyA
Remove titles from the watch history.
Removing an item also wipes its Simkl rating. Anything removed here stops being excluded from recommendations, which is usually the point.
Inputs: type (required), items (required). Returns: object
resolve_idB
Turn an external ID into a Simkl ID -- the cheapest way in.
A TMDB ID needs type ('movie' or 'show'): TMDB IDs are not unique across
movies and TV, so a bare TMDB ID is ambiguous and is refused here.
Reads the 301's Location header without following it, as Simkl requires.
Inputs: mal, imdb, tmdb, type, +1 more. Returns: object
searchA
Search Simkl by title.
type: movie, tv or anime. Omit to search everything.
Titles collide constantly -- "The Bear" is seven distinct works. Treat every result as a candidate to disambiguate by year and type, never as the answer. Prefer resolve_id whenever an external ID is available.
Inputs: query (required), type, limit. Returns: result
set_statusA
Move titles into a watchlist status.
status: watching, plantowatch, hold, completed or dropped.
Two behaviours worth knowing: movies have no watching or hold, and
writing completed for a still-airing show silently becomes watching.
Inputs: type (required), items (required), status (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a clearly distinct purpose: auth (logout, login_status), library retrieval (get_library, get_library_ids, lookup_watched), title info (get_title, search, resolve_id), write actions (mark_watched, set_status, rate, remove_from_history), and sync support (get_activities, get_ratings). Even similar tools like get_library vs get_library_ids are explicitly differentiated by intent (full data vs ID-only for deletion reconciliation).
All tool names follow a consistent snake_case verb-noun pattern (e.g., get_activities, mark_watched, resolve_id). Verbs are uniform across CRUD-like operations, and even standalone verbs like 'search' and 'rate' fit the pattern. No mixed conventions or ambiguous naming.
14 tools is well-scoped for a media library sync and recommendation server. Each tool fills a clear role—auth, reading, writing, ID resolution, and search—without redundancy. The count is neither bloated nor insufficient, covering the full integration surface.
The tool surface covers the entire lifecycle: login status, library synchronization with delta support, deletion reconciliation, direct watched-check, ratings, title details, ID resolution, search, and all write operations (mark, status, rate, remove). No obvious gaps for the stated purpose of powering a recommendation system.
Related MCP Connectors
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Read your tracked time and projects, pause tracking or add a note, from Claude or ChatGPT.
Connect Claude to Fathom meeting recordings, transcripts, and summaries
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables full management of a Plex Media Server via Claude, including browsing libraries, fixing metadata, managing collections, and more.-
- AlicenseNot gradedqualityBmaintenanceEnables Claude to access your Fathom meetings, transcripts, and AI summaries.16MIT
- FlicenseAqualityDmaintenanceProvides Claude AI with direct access to The Movie Database (TMDB) for searching movies, trending content, and reviews through natural language.6-
- AlicenseNot gradedqualityDmaintenanceEnables starting and stopping Clockify timers, checking the currently running timer, and viewing recent time entries via Claude.MIT