{"id":"aa555b3d-4c41-4e15-a262-e0fc5a2a22d0","slug":"vmodal-mcp","kind":"mcp","name":"vmodal-mcp","summary":"MCP server for AI Agent for Multimodal Agent","owner":"v-modal","repoUrl":"https://github.com/v-modal/vmodal_mcp","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-07-14T14:05:05.000Z","addedAt":"2026-10-21T04:49:06.486Z","logoUrl":"https://avatars.githubusercontent.com/u/286898453?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","search"],"tags":["claude-code","claude-code-plugin","codex","mcp-service","video-processing","visual-search","codex-desktop","codex-github"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T06:21:21.948Z","sample":false,"url":"https://conduits.dev/tools/vmodal-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"vmodal_mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"
\n \"VModal\n

VModal MCP

\n

Find moments in your videos by asking your AI assistant.

\n

Works with Claude Code, Codex, Cursor, and GitHub Copilot.

\n
\n\n
\n\n\"A\n\nAfter setup, just ask:\n\n```text\nFind a red car in my city collection.\n```\n\nA **collection** is a group of your videos or images. A **sub-collection** is\na smaller group inside it. You can search a whole collection without choosing\na sub-collection. VModal chooses the search index version automatically.\n\n## Set up once\n\nYou need Python 3.10 or newer and an AI assistant from the list above.\nRun the setup commands in your terminal. After setup, type the prompts in your\nassistant's chat.\n\n### 1. Get your API key\n\n[Sign up for a VModal API key](https://v-modal.com/page/contact.ts).\nCopy your key. Wherever you see `PUT_API_KEY_HERE` below, replace it with your\nkey. Keep your key private.\n\n### 2. Install VModal\n\nFor Claude Code or Codex, install and connect in one command. Choose one and\nenter your API key when prompted:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/v-modal/vmodal_mcp/refs/heads/main/install_mcp.sh | bash -s -- claude\ncurl -fsSL https://raw.githubusercontent.com/v-modal/vmodal_mcp/refs/heads/main/install_mcp.sh | bash -s -- codex\n```\n\nRequires `curl`, `git`, Python with pip, and the selected assistant CLI. You can\nalso export `api_key` before running the command. After it succeeds, skip to\nstep 4.\n\nFor manual installation or another assistant:\n\nCopy this command into your terminal:\n\n```bash\npython -m pip install --upgrade \"git+https://github.com/v-modal/vmodal_mcp.git@main\"\n```\n\n### 3. Connect your assistant\n\nFollow **only the instructions for your assistant**.\n\n#### Claude Code\n\nPaste this into your terminal after replacing `PUT_API_KEY_HERE`:\n\n```bash\nclaude mcp add --scope user vmodal \\\n -e api_key=PUT_API_KEY_HERE -- \\\n vmodal-mcp run --transport stdio\n```\n\n#### Codex\n\nPaste this into your terminal after replacing `PUT_API_KEY_HERE`:\n\n```bash\ncodex mcp add --env api_key=PUT_API_KEY_HERE vmodal -- \\\n vmodal-mcp run --transport stdio\n```\n\n#### GitHub Copilot CLI\n\nPaste this into your terminal after replacing `PUT_API_KEY_HERE`:\n\n```bash\ncopilot mcp add vmodal --env api_key=PUT_API_KEY_HERE -- \\\n vmodal-mcp run --transport stdio\n```\n\n#### Cursor\n\nIn your project, create a file named `.cursor/mcp.json`. Paste the following\ninto it, replace `PUT_API_KEY_HERE` with your key, and save:\n\n```json\n{\n \"mcpServers\": {\n \"vmodal\": {\n \"command\": \"vmodal-mcp\",\n \"args\": [\"run\", \"--transport\", \"stdio\"],\n \"env\": {\n \"api_key\": \"PUT_API_KEY_HERE\"\n }\n }\n }\n}\n```\n\n### 4. Restart your assistant and check the connection\n\nOpen a new chat and paste:\n\n```text\nUse VModal to check my connection and show my account.\n```\n\nIf your assistant shows your account, you're ready.\n\n## Start here: copy a prompt into chat\n\n### See your collections\n\n```text\nList all my collections.\n```\n\n### See your sub-collections\n\n```text\nList all my sub-collections in a table with two columns:\nCollection | Sub-collection\n```\n\n### Find something\n\nReplace `city` with a collection name from your list:\n\n```text\nFind a red car.\nCollection: city\n```\n\nThis searches the whole collection. To search one sub-collection, add its name:\n\n```text\nFind a red car.\nCollection: city\nSub-collection: rome\n```\n\n### Get the matching pictures\n\n```text\nFind a red car in my city collection. Save the best three matching\npictures to my computer and tell me where to find them.\n```\n\n### Upload your first video\n\nReplace `./my_video.mp4` with the path to a video on your computer:\n\n```text\nUpload ./my_video.mp4 to a collection named my_videos, in a sub-collection\nnamed my_uploads. Make it searchable, wait until it's ready, then find\na person walking outside.\n```\n\n[More ready-to-copy prompts →](prompts.md)\n\n## Try it with a sample video (optional)\n\nRun these commands in your terminal, with your API key:\n\n```bash\nexport api_key=PUT_API_KEY_HERE\nvmodal test\n```\n\nThis uploads an included sample video, makes it searchable, and runs a search.\nIt usually takes about a minute. Look for `ok: true` in the result.\nEach run creates a new test collection.\n\n## Need help?\n\n- **VModal doesn't appear in your assistant:** restart your assistant and open a new chat.\n- **Your API key is rejected, or you see `401`:** check the key you entered in step 3.\n- **`vmodal-mcp` or `vmodal` is not found:** restart your terminal and retry. If it still fails, repeat step 2 using the Python installation your terminal uses.\n- **No matches:** ask your assistant to list your collections, check the collection name, and try a simpler description. If you just uploaded a video, ask whether it is ready to search.\n\nFor developer details, see the [tool contract](docs/tool_contract.md).\n"}