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
Markdown
[](/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
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
- # Iris — AI-first movie & TV tracker for iPhone
- Track every movie and TV show you watch, and let Cassandra, an assistant powered by Claude, tell you what to watch
- next: from your own library and your taste, not from a generic top 10.
- > [!WARNING]
- > **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.
- > 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.
- > The AGPL-3.0 licence covers the code only, not TMDB data or artwork.
- <table>
- <tr>
- <td><img src="docs/screenshots/discover.png" width="200" alt="Discover: what's popular on your streaming services"></td>
- <td><img src="docs/screenshots/library.png" width="200" alt="Library: your movies and shows"></td>
- <td><img src="docs/screenshots/detail.png" width="200" alt="A title's detail page"></td>
- <td><img src="docs/screenshots/cassandra.png" width="200" alt="Cassandra, the AI assistant"></td>
- </tr>
- <tr>
- <td align="center">Discover</td>
- <td align="center">Library</td>
- <td align="center">Title detail</td>
- <td align="center">Cassandra</td>
- </tr>
- </table>
- Iris is a native iOS app written in SwiftUI on the [TMDB](https://www.themoviedb.org) API, with a small Cloudflare
- Worker that backs up your library and exposes it as an MCP server, so any AI assistant can work with it too.
- ## Why AI-first
- Most trackers stop at a watchlist. Iris builds an assistant into the app:
- - **Cassandra** is a chat assistant powered by Claude (the Anthropic API, with your own key, kept in the iOS
- Keychain). She streams her answers, shows the steps she takes, and recommends titles you can add in one tap.
- - **She knows your library.** Her tools search TMDB, read a title's details and where it streams in your country, read
- and update your list, and find what's on your streaming services.
- - **A taste portrait.** Iris writes a portrait of your taste as a viewer from your ratings, reviews and history, and
- Cassandra reads it before she recommends anything.
- - **Memories.** Cassandra remembers lasting facts about your taste (likes, dislikes), and you can review or delete them.
- - **Feedback loop.** Every pick is kept with your verdict (seen it, not for me, added), so she doesn't propose the
- same title twice.
- ## MCP server
- The companion API in [`api/`](api) serves a [Model Context Protocol](https://modelcontextprotocol.io) server
- (stateless Streamable HTTP) at `/mcp`. Connect it to Claude or any MCP client and it can read and update the same
- library the app uses; the app picks up the changes the next time it comes to the foreground.
- | Tool | What it does |
- | --- | --- |
- | `search_titles` | Search movies and TV shows on TMDB |
- | `get_title` | A title's details and where it streams, rents or sells |
- | `get_library` | Your list: watchlist and watched, with ratings and reviews |
- | `add_to_library` | Add a movie or show, to the watchlist or as watched |
- | `update_title` | Change a title's status, rating (1–5) or review |
- | `remove_from_library` | Remove a title from the list |
- | `get_show_progress` | Watched episodes season by season, and the next one |
- | `mark_episodes` | Mark episodes watched or unwatched |
- | `get_taste_portrait` | The current taste portrait |
- | `get_taste_material` | What a new portrait is written from, page by page |
- | `save_taste_portrait` | Save a new taste portrait |
- | `list_memories` / `remember` / `forget` | Read and edit Cassandra's memories |
- | `get_recommendation_context` | Portrait, memories, country, services and titles not to propose again |
- | `log_recommendations` | Record the titles just recommended |
- | `set_recommendation_verdict` | Record what the user thought of a pick |
- Authenticate with `Authorization: Bearer <IRIS_MCP_TOKEN>`, or use `/mcp/<IRIS_MCP_TOKEN>` for clients that only take
- a URL.
- ## Features
- - **Movie and TV show tracking:** watchlist, watched, abandoned shows, ratings from 1 to 5 stars and written reviews.
- - **Episode progress:** check off episodes, see what's up next and when new episodes come out.
- - **Discover and Browse:** what's popular on the streaming services you pick, for movies and for shows.
- - **Streaming availability per country:** where each title streams, rents or sells, from TMDB's watch providers.
- - **History import:** bring in your Netflix viewing history and match it to TMDB titles.
- - **Widgets and controls:** Up next, Coming up and a title from your list on the Home Screen, plus Control Center
- controls to open Cassandra or mark the next episode watched.
- - **Siri and Shortcuts:** ask for a movie or show for tonight by mood, mark the next episode watched, add to your list
- or ask Cassandra a question.
- - **Your year:** movies, episodes and active days, month by month, with your streak.
- - **Cloud backup:** the list, episode progress, memories and taste portrait sync to your own API.
- ## Tech stack
- - **App:** SwiftUI, iOS 26, Swift 6 strict concurrency, SwiftData, WidgetKit, App Intents, MV architecture (no view
- models), Swift Testing, SwiftLint
- - **Assistant:** Claude through the Anthropic Messages API, with tool use and streaming
- - **Character:** Cassandra is animated with [Rive](https://rive.app)
- - **Data:** the [TMDB](https://www.themoviedb.org) API
- - **API:** Cloudflare Workers (TypeScript) on [Turso](https://turso.tech) (libSQL), with the MCP server
- ## Getting started
- ### 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.
- ```bash
- xcodebuild test -project Iris.xcodeproj -scheme Iris -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' -skipPackagePluginValidation
- ```
- ### API and MCP server
- ```bash
- 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`.
- ## Contributing
- Issues and pull requests are welcome. Please keep SwiftLint clean (it runs on every build), add tests with your
- change, and keep build settings in `Config/Shared.xcconfig` rather than in the project file.
- ## Acknowledgements
- 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.
- 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.
- ## License
- 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 inFree to use. If it’s helped, pass it on.