Package Exports

@perceptron-ai/mcp-server
@perceptron-ai/mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@perceptron-ai/mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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`	Visual question answering — ask a question about an image or video (requires `modality`)
`caption`	Captioning — generate concise or detailed descriptions of an image or video (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), or a base64 data URI (data:image/jpeg;base64,...) for images or videos, and require a modality parameter ("image" or "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, and WebM.

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.

Troubleshooting

"PERCEPTRON_API_KEY environment variable is required"

Set the PERCEPTRON_API_KEY environment variable in your MCP client configuration.

"Unrecognized file extension"

The file extension could not be mapped to a MIME type. Rename the file with a standard extension (e.g. .jpg, .png, .webp).

Connection errors to the remote server

Verify your API key is valid and that you can reach https://api.perceptron.inc. If you need a custom endpoint, set PERCEPTRON_BASE_URL.

File not found errors

Ensure the file path is absolute or starts with ~. Relative paths are resolved from the server's working directory.

Development

# Install dependencies
npm install

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

# Build
npm run build

# Run tests
npm test

License

Apache License 2.0