English Français العربية

Filimo and Namava

Official registry Search and web

Read-only Filimo and Namava catalogs: search, title details, episodes, new, genres, where to watch.

Source code Website Documentation

What can you do with Filimo and Namava?

  • "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?"
  • فیلم بینوایان در نماوا هست؟ کارگردانش کیست؟
  • سریال‌های ایرانی با بیشترین امتیاز در فیلیمو کدامند؟

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package iran-vod-mcp
Claude Code 
claude mcp add filimo-and-namava -e 'IRAN_VOD_MCP_PROXY=<IRAN_VOD_MCP_PROXY>' -- uvx iran-vod-mcp==0.1.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "filimo-and-namava": {
            "command": "uvx",
            "args": [
                "iran-vod-mcp==0.1.1"
            ],
            "env": {
                "IRAN_VOD_MCP_PROXY": "<IRAN_VOD_MCP_PROXY>"
            }
        }
    }
}

Environment variables

  • IRAN_VOD_MCP_PROXY Optional HTTP proxy URL for the Filimo and Namava requests; system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. iran-vod-mcp: Filimo (فیلیمو) and Namava (نماوا) catalog MCP server for AI agents
  2. For AI agents
  3. Quick start
  4. Tools
  5. FAQ
  6. فارسی
  7. License

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

ToolWhat it does
vod_searchSearch Filimo, Namava or both by title; movies and series with a ref each
vod_whereWhich of the two services carries a title (exact and similar matches per site)
vod_titleSynopsis, genres, year, rating, age rating, country, cast and director of one title
vod_episodesSeasons of a series and the episodes of one season (summary, length, date)
vod_newNewest titles per service, movies or series
vod_featuredWhat each front page promotes: Filimo rows (popular, box office, genres), Namava hero slider and top list
vod_browseTitles of one genre; Filimo also sorts (rating, IMDb, year, newest added) and filters by country
vod_genresGenre names, aliases, sort and country values
vod_personAn actor or director: bio and the titles they appear in, on Filimo and Namava
vod_relatedTitles similar to one title; Filimo also names its featured actors and writers
vod_collectionsCurated lists you can open: IMDb top 250, festival winners, kids, Oscar, true stories, coming soon
vod_collectionThe titles of one curated list (Filimo sort and country filters, paging to about 200 titles)
vod_plansNamava 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.

فارسی

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

License

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

Frequently asked questions

What is Filimo and Namava?

Read-only Filimo and Namava catalogs: search, title details, episodes, new, genres, where to watch.

How do I install Filimo and Namava?

It runs on your machine. In Claude Code: claude mcp add filimo-and-namava -e 'IRAN_VOD_MCP_PROXY=<IRAN_VOD_MCP_PROXY>' -- uvx iran-vod-mcp==0.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Filimo and Namava need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Filimo and Namava open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Filimo and Namava?

It is published by sepehr071. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.