Filimo and Namava

iran-vod-mcp: Filimo (فیلیمو) and Namava (نماوا) catalog MCP server for AI agents

iran-vod-mcp is an unofficial, read-only MCP server that gives AI agents the public movie and series catalogs of Filimo and Namava.

Its 13 tools search both services, tell you which one carries a title, read synopsis, rating, cast and age rating,

list seasons and episodes, look up actors and directors, find similar titles, open curated lists (IMDb top 250, Oscar, kids,

coming soon), browse genres and show Namava subscription prices.

No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.

For AI agents · Quick start · Tools · FAQ · فارسی

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.

فارسی

iran-vod-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای فهرست فیلم و سریال فیلیمو و نماوا است: جستجوی عنوان در هر دو سرویس، اینکه یک عنوان در کدام سرویس هست، خلاصه داستان، امتیاز، رده سنی، بازیگران، فصل‌ها و قسمت‌ها، تازه‌ها و دسته‌بندی ژانر. پخش، دانلود و ورود به حساب پشتیبانی نمی‌شود. نصب: uvx iran-vod-mcp

License

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