DINO-X MCP server for AI agents

DINO-X MCP allows large language models to perform fine-grained object detection and image understanding through the DINO-X and Grounding DINO 1.6 API. This tool enables precise localization, high-quality structured outputs, and accurate object detection to enhance visual understanding tasks and build multi-step visual workflows.

Installation

Prerequisites

You need to have Node.js installed on your system. Here are two installation options:

Option A: Command Line Installation (Recommended)

For MacOS or Linux:

# 1. Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# OR
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 2. Add these lines to your profile
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  

# 3. Activate nvm in current shell
source ~/.bashrc
# Or
source ~/.zshrc   

# 4. Install and use LTS version of Node.js
nvm install --lts
nvm use --lts

For Windows:

winget install OpenJS.NodeJS.LTS
# Or using PowerShell (Administrator)
iwr -useb https://raw.githubusercontent.com/chocolatey/chocolatey/master/chocolateyInstall/InstallChocolatey.ps1 | iex
choco install nodejs-lts -y

Option B: Manual Installation

Download and install Node.js directly from nodejs.org.

Server Configuration

You can set up the DINO-X MCP server in two ways:

Option A: Using NPM Package (Recommended)

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "dinox-mcp": {
      "command": "npx",
      "args": ["-y", "@deepdataspace/dinox-mcp"],
      "env": {
        "DINOX_API_KEY": "your-api-key-here",
        "IMAGE_STORAGE_DIRECTORY": "/path/to/your/image/directory"
      }
    }
  }
}

Option B: Using Local Project

Clone and build the project:

# Clone the project
git clone https://github.com/IDEA-Research/DINO-X-MCP.git
cd DINO-X-MCP

# Install dependencies
pnpm install

# Build the project
pnpm run build

Then configure your MCP client:

{
  "mcpServers": {
    "dinox-mcp": {
      "command": "node",
      "args": ["/path/to/DINO-X-MCP/build/index.js"],
      "env": {
        "DINOX_API_KEY": "your-api-key-here",
        "IMAGE_STORAGE_DIRECTORY": "/path/to/your/image/directory"
      }
    }
  }
}

Get API Key

Obtain your API key from the DINO-X Platform. New users receive a free quota.

Replace your-api-key-here in the configuration with your actual API key.

Environment Variables

The server supports these environment variables:

Variable Name	Description	Required	Default Value
`DINOX_API_KEY`	Your DINO-X API key	Required	-
`IMAGE_STORAGE_DIRECTORY`	Directory for saving visualization images	Optional	macOS/Linux: `/tmp/dinox-mcp` Windows: `%TEMP%\dinox-mcp`

Using DINO-X MCP

Available Tools

After configuring and restarting your MCP client, you can use these tools:

Method Name	Description	Input	Output
`detect-all-objects`	Detects all recognizable objects in an image	Image	Category names + bounding boxes + captions
`object-detection-by-text`	Detects objects based on a natural language prompt	Image + Text prompt	Bounding boxes + object captions
`detect-human-pose-keypoints`	Detects 17 human body keypoints per person	Image	Keypoint coordinates and captions
`visualize-detections`	Visualizes detection results on the image	Image + Detection results	Annotated image saved to storage directory

Supported Image Formats

Remote URLs starting with https:// (recommended)
Local file paths (starting with file://)
Common image formats: jpg, jpeg, png, webp

MCP Client Compatibility

DINO-X MCP works with these AI assistants and applications:

For detailed API usage limits and pricing information, visit the DINO-X Platform documentation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "dinox-mcp" '{"command":"npx","args":["-y","@deepdataspace/dinox-mcp"],"env":{"DINOX_API_KEY":"your-api-key-here","IMAGE_STORAGE_DIRECTORY":"/path/to/your/image/directory"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "dinox-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@deepdataspace/dinox-mcp"
            ],
            "env": {
                "DINOX_API_KEY": "your-api-key-here",
                "IMAGE_STORAGE_DIRECTORY": "/path/to/your/image/directory"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "dinox-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@deepdataspace/dinox-mcp"
            ],
            "env": {
                "DINOX_API_KEY": "your-api-key-here",
                "IMAGE_STORAGE_DIRECTORY": "/path/to/your/image/directory"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect