0.3.0 • Published 10h agoCLI

@perceptron-ai/mcp-server

Licence

Apache-2.0

Version

0.3.0

Deps

Size

35 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Perceptron Vision MCP Server

A vision MCP server by Perceptron — high-accuracy vision AI over the Model Context Protocol, powered by fast, efficient vision-language models.

Give any MCP-compatible agent direct access to Perceptron's Isaac model family for visual question answering, captioning, OCR, and object detection over images and videos.

Available Tools

Tool	Description
`question`	Question answering — ask a question about an image, video, or audio clip (requires `modality`)
`caption`	Captioning — generate concise or detailed descriptions of an image, video, or audio clip (requires `modality`)
`ocr`	Text extraction — pull text from images as plain text, markdown, or HTML (image-only)
`detect`	Object detection — locate and classify objects in an image or video, optionally filtered by class (requires `modality`)
`list_models`	List available Perceptron models and their capabilities

question, caption, and detect accept a URL (https://...), a local file path (/path/to/clip.mp4, ~/photos/image.png, ~/recordings/call.wav), or a base64 data URI (data:image/jpeg;base64,...), and require a modality parameter ("image", "video", or "audio"; detect accepts image and video). ocr is image-only and uses an image_url parameter. Local files are automatically uploaded to the Perceptron platform before analysis. Currently supported formats: JPEG, PNG, WebP, MP4, WebM, WAV, MP3, and FLAC.

Video soundtracks are ignored unless enable_audio_in_video: true is set with modality: "video" on question or caption. Every tool accepts reasoning_effort ("none", "minimal", "low", "medium", or "high") to control how much the model reasons before answering; the boolean reasoning parameter is deprecated in its favor.

Model Selection

The model parameter is optional — if omitted, the default Perceptron model is used. Call list_models to discover all available models and their capabilities.

Configuration

Required

Variable	Description
`PERCEPTRON_API_KEY`	Your Perceptron API key

Get your API key from the Perceptron dashboard.

Optional

Variable	Default	Description
`PERCEPTRON_BASE_URL`	`https://api.perceptron.inc`	Custom API endpoint

Installation

Claude Code

claude mcp add perceptron -e PERCEPTRON_API_KEY=your-api-key -- npx -y @perceptron-ai/mcp-server@latest

Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "perceptron": {
      "command": "npx",
      "args": ["-y", "@perceptron-ai/mcp-server@latest"],
      "env": {
        "PERCEPTRON_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "perceptron": {
      "command": "npx",
      "args": ["-y", "@perceptron-ai/mcp-server@latest"],
      "env": {
        "PERCEPTRON_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "perceptron": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perceptron-ai/mcp-server@latest"],
      "env": {
        "PERCEPTRON_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "perceptron": {
      "command": "npx",
      "args": ["-y", "@perceptron-ai/mcp-server@latest"],
      "env": {
        "PERCEPTRON_API_KEY": "your-api-key"
      }
    }
  }
}

Google Antigravity

Add to your Antigravity MCP configuration (~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "perceptron": {
      "command": "npx",
      "args": ["-y", "@perceptron-ai/mcp-server@latest"],
      "env": {
        "PERCEPTRON_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

codex mcp add perceptron --env PERCEPTRON_API_KEY=your-api-key -- npx -y @perceptron-ai/mcp-server@latest

Generic MCP Clients

PERCEPTRON_API_KEY=your-api-key npx -y @perceptron-ai/mcp-server@latest

Note: The @latest tag ensures you always get the newest models and tools. To pin a specific version, replace @latest with a version number from npm (e.g. @perceptron-ai/mcp-server@0.1.5).

How Local Files Work

When you pass a local file path as media_url (or image_url for ocr), the server transparently:

Reads the file from disk
Requests a presigned upload URL from the Perceptron platform
Uploads the file
Obtains a presigned download URL
Passes the download URL to the model for analysis

This means you can analyze images and videos on your machine without manual upload steps.

# Install dependencies
npm install

# Run in development mode
PERCEPTRON_API_KEY=your-key npm run dev

# Build
npm run build

# Run tests
npm test

Release notes

0.3.0

Added: modality: "audio" on question and caption (WAV, MP3, FLAC), and enable_audio_in_video to analyze a video's soundtrack alongside its frames.
Added: reasoning_effort (none, minimal, low, medium, high) on every tool. The boolean reasoning parameter is deprecated.
Changed: When model is omitted, tools default to perceptron-mk1.5 (previously perceptron-mk1). Pass model: "perceptron-mk1" to keep the previous behavior.
Changed: caption without output_format returns plain text for video and audio (previously boxes for video). Image captions still default to boxes. Pass output_format: "box" to keep the previous behavior on video.