\n\n**Control FiftyOne datasets through AI assistants using the Model Context Protocol**\n\n[](LICENSE)\n[](https://pypi.org/project/fiftyone-mcp-server/)\n[](https://pypi.org/project/fiftyone-mcp-server/)\n\n[](https://discord.gg/fiftyone-community)\n[](https://huggingface.co/Voxel51)\n[](https://voxel51.com/blog)\n[](https://share.hsforms.com/1zpJ60ggaQtOoVeBqIZdaaA2ykyk)\n[](https://www.linkedin.com/company/voxel51)\n[](https://x.com/voxel51)\n[](https://medium.com/voxel51)\n\n[Documentation](https://docs.voxel51.com) ยท [FiftyOne Skills](https://github.com/voxel51/fiftyone-skills) ยท [FiftyOne Plugins](https://github.com/voxel51/fiftyone-plugins) ยท [Discord](https://discord.gg/fiftyone-community)\n\n
\n\n## What is the FiftyOne MCP Server?\n\nEnable Agents to explore datasets, execute operators, and control the FiftyOne App through natural language. This server exposes 45+ MCP tools across data operations, App UI control, and the full operator/plugin ecosystem.\n\n```\n\"List all my datasets\"\n\"Load quickstart dataset and show summary\"\n\"Find similar images in my dataset\"\n```\n\nThe server starts with 50 built-in operators. Install plugins to expand functionality - the AI can discover and install plugins automatically when needed (brain, zoo, annotation, evaluation, and more).\n\n## Available Tools\n\n| Category | Tools | Description |\n| ------------------------- | ----- | -------------------------------------------------- |\n| ๐ **Dataset Management** | 3 | List, load, and summarize datasets |\n| ๐ฏ **App Operations** | 29 | Control the App UI (views, panels, selection, ...) |\n| โก **Operator System** | 3 | Discover and execute any FiftyOne operator |\n| ๐ **Pipelines** | 2 | Run pipelines and manage delegated operations |\n| ๐ **Plugin Management** | 5 | Discover, install, and manage plugins |\n| ๐ฅ๏ธ **Session** | 1 | Launch the FiftyOne App server |\n| ๐ **Aggregations** | 8 | Count, distinct, bounds, mean, histogram, ... |\n| ๐งฌ **Samples** | 5 | Add, tag, untag, and set values on samples |\n| ๐๏ธ **Schema** | 2 | Inspect and modify dataset field schemas |\n| ๐จ **App Config** | 6 | Color scheme, sidebar groups, active fields |\n\n### Tool modes\n\n45+ tools organized by runtime mode:\n\n- **SDK**: Data operations that work everywhere (datasets, aggregations, schema, samples, operators, plugins). No App connection needed.\n- **APP**: Controls the FiftyOne App UI in real time (set_view, open_panel, notify, select_samples, reload, and 25+ more). Requires a connected browser via `ctx.ops`.\n- **SESSION**: Bootstrap tools for starting a local App server (launch_app). Used from terminal environments.\n\n### Choosing your tools\n\nWhich tools are available depends on how you integrate the server:\n\n| Integration | Modes | Use case |\n| ----------------------- | ----------------- | -------------------------------------------------------------- |\n| **FiftyOne App plugin** | `app` + `sdk` | Agent panel inside the App (full UI control + data operations) |\n| **Terminal / CLI** | `session` + `sdk` | Headless agent (launch the App, query data, execute operators) |\n\n### Tool risk levels\n\nEvery tool is tagged with a risk level that your agent can use for auto-approval decisions:\n\n- **`LOW`** Safe to auto-execute without prompting (read-only queries, UI state changes)\n- **`OPERATOR`** Wraps a FiftyOne operator whose own severity should be checked before executing\n\n## Quick Start\n\n### Step 1: Install the MCP Server\n\n```bash\npip install fiftyone-mcp-server\n```\n\n> **โ ๏ธ Important:** Make sure to use the same Python environment where you installed the MCP server when configuring your AI tool. If you installed it in a virtual environment or conda environment, you must activate that environment or specify the full path to the executable.\n\n### Step 2: Configure Your AI Tool\n\n\nClaude Code (Recommended)\n\n```bash\nclaude mcp add fiftyone -- fiftyone-mcp\n```\n\n\n\n\nClaude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"fiftyone\": {\n \"command\": \"fiftyone-mcp\"\n }\n }\n}\n```\n\n\n\n\nCursor\n\n[](cursor://anysphere.cursor-deeplink/mcp/install?name=fiftyone&config=eyJjb21tYW5kIjoiZmlmdHlvbmUtbWNwIn0)\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"fiftyone\": {\n \"command\": \"fiftyone-mcp\"\n }\n }\n}\n```\n\n\n\n\nVSCode\n\n[](https://insiders.vscode.dev/redirect/mcp/install?name=fiftyone&config=%7B%22command%22%3A%22fiftyone-mcp%22%7D)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"fiftyone\": {\n \"command\": \"fiftyone-mcp\"\n }\n }\n}\n```\n\n\n\n\nChatGPT Desktop\n\nEdit `~/Library/Application Support/ChatGPT/config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"fiftyone\": {\n \"command\": \"fiftyone-mcp\"\n }\n }\n}\n```\n\n\n\n\nuvx (No Install Needed)\n\nIf you have [uv](https://github.com/astral-sh/uv) installed:\n\n```json\n{\n \"mcpServers\": {\n \"fiftyone\": {\n \"command\": \"uvx\",\n \"args\": [\"fiftyone-mcp-server\"]\n }\n }\n}\n```\n\nThis downloads and runs the latest version automatically.\n\n\n\n### Step 3: Use It\n\n```\n\"List all my datasets\"\n\"Load quickstart dataset and show summary\"\n\"Open the map panel and show me the embeddings\"\n\"Select samples with confidence above 0.9\"\n\"What plugins are available? Install the brain plugin\"\n\"Find near-duplicate images in my dataset\"\n```\n\nClaude will automatically discover operators and execute the appropriate tools.\n\n## Contributing\n\nWe welcome contributions! Here's how to set up a local development environment:\n\n1. **Clone** the repository\n\n ```bash\n git clone https://github.com/voxel51/fiftyone-mcp-server.git\n cd fiftyone-mcp-server\n ```\n\n2. **Install** dependencies\n\n ```bash\n poetry install\n ```\n\n3. **Run** the server locally\n\n ```bash\n poetry run fiftyone-mcp\n ```\n\n4. **Test** your changes\n\n ```bash\n poetry run pytest\n poetry run black -l 79 src/\n npx @modelcontextprotocol/inspector poetry run fiftyone-mcp\n ```\n\n5. **Submit** a Pull Request\n\n## Resources\n\n| Resource | Description |\n| --------------------------------------------------------------- | ---------------------------------- |\n| [FiftyOne Docs](https://docs.voxel51.com) | Official documentation |\n| [FiftyOne Skills](https://github.com/voxel51/fiftyone-skills) | Expert workflows for AI assistants |\n| [FiftyOne Plugins](https://github.com/voxel51/fiftyone-plugins) | Official plugin collection |\n| [Model Context Protocol](https://modelcontextprotocol.io) | MCP specification |\n| [PyPI Package](https://pypi.org/project/fiftyone-mcp-server/) | MCP server on PyPI |\n| [Discord Community](https://discord.gg/fiftyone-community) | Get help and share ideas |\n\n## Community\n\nJoin the FiftyOne community to get help, share your ideas, and connect with other users:\n\n- **Discord**: [FiftyOne Community](https://discord.gg/fiftyone-community)\n- **GitHub Issues**: [Report bugs or request features](https://github.com/voxel51/fiftyone-mcp-server/issues)\n\n---\n\n
\n\nCopyright 2017-2026, Voxel51, Inc. ยท [Apache 2.0 License](LICENSE)\n\n
![](\"https://user-images.githubusercontent.com/25985824/106288517-2422e000-6216-11eb-871d-26ad2e7b1e59.png\")
\n![](\"https://user-images.githubusercontent.com/25985824/106288518-24bb7680-6216-11eb-8f10-60052c519586.png\")
\n\n