Filimo and Namava

---

For AI agents

• What: unofficial MCP server (model context protocol) for filimo.com and namava.ir, the two big Iranian video-on-demand services: title search, "which service has this title", title details, series seasons and episodes, actor and director filmographies, similar titles, curated lists, new releases, front-page picks, genre browsing, Namava plans.
• Install: uvx iran-vod-mcp or claude mcp add iran-vod -- uvx iran-vod-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none. Optional IRAN_VOD_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
• Access: read-only catalog data. It cannot log in, play video, give stream links or change anything, so no confirmation is needed before calling any tool.
• Tools: 13, all prefixed vod_. Typical sequences: vod_search -> vod_title -> vod_episodes / vod_related / vod_person; vod_where for one title; vod_browse -> vod_title; vod_collections -> vod_collection.
• Use when: the user asks if a film or series is on Filimo or Namava, what it is about, who is in it, its rating or age rating, how many seasons or episodes it has, what is new or popular, or what to watch in a genre.
• Do not use when: the user wants to watch, download or get stream links, or needs Filimo prices (only Namava plans are public JSON).
• Output: compact JSON. Years are Persian-calendar as the sites show them (foreign titles show the Gregorian year). Ratings differ: Filimo stars out of 5 with a vote count and IMDb, Namava like and dislike counts. Text is Persian site content.
• Machine-readable: server.json.

Quick start

claude mcp add iran-vod -- uvx iran-vod-mcp

Or in any MCP client config:

{ "mcpServers": { "iran-vod": { "command": "uvx", "args": ["iran-vod-mcp"] } } }

Both sites answer from Iran directly. Foreign (licensed) titles are only listed to Iranian IP addresses: from abroad you see the Iranian catalog only. If you need a proxy, set IRAN_VOD_MCP_PROXY=http://host:port.

Tools

Tool	What it does
vod_search	Search Filimo, Namava or both by title; movies and series with a ref each
vod_where	Which of the two services carries a title (exact and similar matches per site)
vod_title	Synopsis, genres, year, rating, age rating, country, cast and director of one title
vod_episodes	Seasons of a series and the episodes of one season (summary, length, date)
vod_new	Newest titles per service, movies or series
vod_featured	What each front page promotes: Filimo rows (popular, box office, genres), Namava hero slider and top list
vod_browse	Titles of one genre; Filimo also sorts (rating, IMDb, year, newest added) and filters by country
vod_genres	Genre names, aliases, sort and country values
vod_person	An actor or director: bio and the titles they appear in, on Filimo and Namava
vod_related	Titles similar to one title; Filimo also names its featured actors and writers
vod_collections	Curated lists you can open: IMDb top 250, festival winners, kids, Oscar, true stories, coming soon
vod_collection	The titles of one curated list (Filimo sort and country filters, paging to about 200 titles)
vod_plans	Namava subscription plans and prices (Filimo prices are not in its JSON API)

Example prompts:

• "Is Iranian Dinner (شام ایرانی) on Filimo or Namava, and how many seasons?"
• "Best-rated Iranian comedy series on Filimo."
• "What is new on Namava this week?"
• "What has Parsa Pirouzfar acted in on Filimo?" / "What is coming soon to Namava?"
• فیلم بینوایان در نماوا هست؟ کارگردانش کیست؟
• سریال‌های ایرانی با بیشترین امتیاز در فیلیمو کدامند؟

FAQ

Can it play or download videos? No. It lists and describes titles only; no stream or download URLs are fetched.

Why do I see fewer titles from abroad? Both services hide licensed foreign titles from non-Iranian IP addresses.

Why does a Filimo series show only a few actors? Filimo has no cast list. For a movie the names come from its description text; for a series they are the actors Filimo features on the series page (usually two or three).

Is it affiliated with Filimo or Namava? No. It reads the same public JSON the websites use, at a polite rate with a short cache.

فارسی

License

MIT. Author: Sepehr Radmard (سپهر رادمرد), github.com/sepehr071, linkedin.com/in/sepehr-radmard.