Skip to content
Back to search

iris-tracker

AI-first movie & TV tracker for iPhone: SwiftUI app with a Claude-powered assistant and an MCP server for your watchlist, episodes and taste.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/powpowchuuuu--iris-tracker/badge.svg)](/listings/powpowchuuuu--iris-tracker)

HTML

<a href="/listings/powpowchuuuu--iris-tracker"><img src="/api/listings/powpowchuuuu--iris-tracker/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

App

1. `cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig` and set `TMDB_API_KEY`. 2. Set your own bundle identifier prefix (`com.example.Iris`), App Group and development team in Xcode. 3. Optional: point `IRIS_API_URL` in `Config/Shared.xcconfig` at your own deployment of `api/` and set `IRIS_API_KEY` in `Secrets.xcconfig`. Sync only runs on a real device; the simulator keeps its data local. 4. Build and run the `Iris` scheme. To chat with Cassandra, add your Anthropic API key in Settings.

xcodebuild test -project Iris.xcodeproj -scheme Iris -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' -skipPackagePluginValidation

API and MCP server

cd api
npm install
turso db create iris
npm run migrate                          # applies migrations/ with the turso CLI
npx wrangler secret put TURSO_DATABASE_URL
npx wrangler secret put TURSO_AUTH_TOKEN
npx wrangler secret put IRIS_API_KEY     # the app's key
npx wrangler secret put IRIS_MCP_TOKEN   # the MCP server's token
npx wrangler secret put TMDB_API_KEY
npm run deploy

For a local run, put the same values in `api/.dev.vars` and run `npx wrangler dev`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 137 lines
  1. # Iris — AI-first movie & TV tracker for iPhone
  2. Track every movie and TV show you watch, and let Cassandra, an assistant powered by Claude, tell you what to watch
  3. next: from your own library and your taste, not from a generic top 10.
  4. > [!WARNING]
  5. > **Personal, non-commercial concept: do not publish this app as-is.** Iris is not affiliated with TMDB, Anthropic or any streaming service. To run it, bring your own TMDB and Anthropic keys; none ship with this repo.
  6. > Sending TMDB data to an AI (Cassandra, the MCP server) is restricted by [TMDB's API Terms](https://www.themoviedb.org/api-terms-of-use). Any public or commercial release (App Store, TestFlight, web) needs a written agreement with TMDB, and TMDB data may not be cached for more than 6 months.
  7. > The AGPL-3.0 licence covers the code only, not TMDB data or artwork.
  8. <table>
  9. <tr>
  10. <td><img src="docs/screenshots/discover.png" width="200" alt="Discover: what's popular on your streaming services"></td>
  11. <td><img src="docs/screenshots/library.png" width="200" alt="Library: your movies and shows"></td>
  12. <td><img src="docs/screenshots/detail.png" width="200" alt="A title's detail page"></td>
  13. <td><img src="docs/screenshots/cassandra.png" width="200" alt="Cassandra, the AI assistant"></td>
  14. </tr>
  15. <tr>
  16. <td align="center">Discover</td>
  17. <td align="center">Library</td>
  18. <td align="center">Title detail</td>
  19. <td align="center">Cassandra</td>
  20. </tr>
  21. </table>
  22. Iris is a native iOS app written in SwiftUI on the [TMDB](https://www.themoviedb.org) API, with a small Cloudflare
  23. Worker that backs up your library and exposes it as an MCP server, so any AI assistant can work with it too.
  24. ## Why AI-first
  25. Most trackers stop at a watchlist. Iris builds an assistant into the app:
  26. - **Cassandra** is a chat assistant powered by Claude (the Anthropic API, with your own key, kept in the iOS
  27. Keychain). She streams her answers, shows the steps she takes, and recommends titles you can add in one tap.
  28. - **She knows your library.** Her tools search TMDB, read a title's details and where it streams in your country, read
  29. and update your list, and find what's on your streaming services.
  30. - **A taste portrait.** Iris writes a portrait of your taste as a viewer from your ratings, reviews and history, and
  31. Cassandra reads it before she recommends anything.
  32. - **Memories.** Cassandra remembers lasting facts about your taste (likes, dislikes), and you can review or delete them.
  33. - **Feedback loop.** Every pick is kept with your verdict (seen it, not for me, added), so she doesn't propose the
  34. same title twice.
  35. ## MCP server
  36. The companion API in [`api/`](api) serves a [Model Context Protocol](https://modelcontextprotocol.io) server
  37. (stateless Streamable HTTP) at `/mcp`. Connect it to Claude or any MCP client and it can read and update the same
  38. library the app uses; the app picks up the changes the next time it comes to the foreground.
  39. | Tool | What it does |
  40. | --- | --- |
  41. | `search_titles` | Search movies and TV shows on TMDB |
  42. | `get_title` | A title's details and where it streams, rents or sells |
  43. | `get_library` | Your list: watchlist and watched, with ratings and reviews |
  44. | `add_to_library` | Add a movie or show, to the watchlist or as watched |
  45. | `update_title` | Change a title's status, rating (1–5) or review |
  46. | `remove_from_library` | Remove a title from the list |
  47. | `get_show_progress` | Watched episodes season by season, and the next one |
  48. | `mark_episodes` | Mark episodes watched or unwatched |
  49. | `get_taste_portrait` | The current taste portrait |
  50. | `get_taste_material` | What a new portrait is written from, page by page |
  51. | `save_taste_portrait` | Save a new taste portrait |
  52. | `list_memories` / `remember` / `forget` | Read and edit Cassandra's memories |
  53. | `get_recommendation_context` | Portrait, memories, country, services and titles not to propose again |
  54. | `log_recommendations` | Record the titles just recommended |
  55. | `set_recommendation_verdict` | Record what the user thought of a pick |
  56. Authenticate with `Authorization: Bearer <IRIS_MCP_TOKEN>`, or use `/mcp/<IRIS_MCP_TOKEN>` for clients that only take
  57. a URL.
  58. ## Features
  59. - **Movie and TV show tracking:** watchlist, watched, abandoned shows, ratings from 1 to 5 stars and written reviews.
  60. - **Episode progress:** check off episodes, see what's up next and when new episodes come out.
  61. - **Discover and Browse:** what's popular on the streaming services you pick, for movies and for shows.
  62. - **Streaming availability per country:** where each title streams, rents or sells, from TMDB's watch providers.
  63. - **History import:** bring in your Netflix viewing history and match it to TMDB titles.
  64. - **Widgets and controls:** Up next, Coming up and a title from your list on the Home Screen, plus Control Center
  65. controls to open Cassandra or mark the next episode watched.
  66. - **Siri and Shortcuts:** ask for a movie or show for tonight by mood, mark the next episode watched, add to your list
  67. or ask Cassandra a question.
  68. - **Your year:** movies, episodes and active days, month by month, with your streak.
  69. - **Cloud backup:** the list, episode progress, memories and taste portrait sync to your own API.
  70. ## Tech stack
  71. - **App:** SwiftUI, iOS 26, Swift 6 strict concurrency, SwiftData, WidgetKit, App Intents, MV architecture (no view
  72. models), Swift Testing, SwiftLint
  73. - **Assistant:** Claude through the Anthropic Messages API, with tool use and streaming
  74. - **Character:** Cassandra is animated with [Rive](https://rive.app)
  75. - **Data:** the [TMDB](https://www.themoviedb.org) API
  76. - **API:** Cloudflare Workers (TypeScript) on [Turso](https://turso.tech) (libSQL), with the MCP server
  77. ## Getting started
  78. ### App
  79. 1. `cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig` and set `TMDB_API_KEY`.
  80. 2. Set your own bundle identifier prefix (`com.example.Iris`), App Group and development team in Xcode.
  81. 3. Optional: point `IRIS_API_URL` in `Config/Shared.xcconfig` at your own deployment of `api/` and set
  82. `IRIS_API_KEY` in `Secrets.xcconfig`. Sync only runs on a real device; the simulator keeps its data local.
  83. 4. Build and run the `Iris` scheme. To chat with Cassandra, add your Anthropic API key in Settings.
  84. ```bash
  85. xcodebuild test -project Iris.xcodeproj -scheme Iris -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' -skipPackagePluginValidation
  86. ```
  87. ### API and MCP server
  88. ```bash
  89. cd api
  90. npm install
  91. turso db create iris
  92. npm run migrate # applies migrations/ with the turso CLI
  93. npx wrangler secret put TURSO_DATABASE_URL
  94. npx wrangler secret put TURSO_AUTH_TOKEN
  95. npx wrangler secret put IRIS_API_KEY # the app's key
  96. npx wrangler secret put IRIS_MCP_TOKEN # the MCP server's token
  97. npx wrangler secret put TMDB_API_KEY
  98. npm run deploy
  99. ```
  100. For a local run, put the same values in `api/.dev.vars` and run `npx wrangler dev`.
  101. ## Contributing
  102. Issues and pull requests are welcome. Please keep SwiftLint clean (it runs on every build), add tests with your
  103. change, and keep build settings in `Config/Shared.xcconfig` rather than in the project file.
  104. ## Acknowledgements
  105. The UI is inspired by [Binge – Movies and Shows](https://apps.apple.com/fr/app/binge-movies-and-shows/id6755895331). Iris is an independent project, not affiliated with Binge or its developers.
  106. Movie and show data and images come from [TMDB](https://www.themoviedb.org). This product uses the TMDB API but is not endorsed or certified by TMDB.
  107. ## License
  108. Iris is free software, licensed under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.