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

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.