ivedaai-mcp-server

An MCP server for the IvedaAI video analytics API. Point an MCP client — Claude Desktop, Claude Code, or anything else that speaks the protocol — at your IvedaAI deployment and drive it in natural language: search footage, manage cameras and alert rules, run analysis jobs, work with face and licence-plate watchlists.

316 API operations are exposed as 63 tools, one per resource type. See why.

Quickstart

Add this to your MCP client's configuration. Nothing to install first — npx fetches it.

{
  "mcpServers": {
    "ivedaai": {
      "command": "npx",
      "args": ["-y", "ivedaai-mcp-server"],
      "env": {
        "IVEDAAI_BASE_URL": "https://ivedaai.example.com",
        "IVEDAAI_USERNAME": "your-username",
        "IVEDAAI_PASSWORD": "your-password"
      }
    }
  }
}

Where that file lives:

Restart the client, and ask it something like "list the cameras that are currently offline".

Try it without a client:

IVEDAAI_BASE_URL=https://ivedaai.example.com \
IVEDAAI_USERNAME=you IVEDAAI_PASSWORD=secret \
npx -y ivedaai-mcp-server

It speaks JSON-RPC over stdin/stdout and logs a startup line to stderr. --help prints the configuration reference; --version prints the version.

Related MCP server: Discovery Engine MCP Server

Read-only first

If you are evaluating this, or connecting it to anything you would not want to write to, start here:

"env": { "IVEDAAI_READ_ONLY": "true", "IVEDAAI_BASE_URL": "…", "IVEDAAI_USERNAME": "…", "IVEDAAI_PASSWORD": "…" }

Every non-GET is withheld from the tool list entirely rather than merely refused, and it roughly halves what the tool descriptions cost on connect.

Configuration

Only the first three are required.

Copy .env.example if you prefer a file.

Authentication

OAuth2 password grant against POST {base}/ainvr/api/oauth2/token. The server logs in on first use, caches the access token, and refreshes it as it nears expiry. Note that the token endpoint is rate limited: a client that starts a fresh process per request will hit it.

Destructive operations

Twenty of this API's DELETEs take no id in the path — DELETE /api/cameras versus DELETE /api/cameras/{cameraId}. The only subject would come from an optional request body, and what the API does when that body is omitted is not specified anywhere. One character of difference, and the mistake cannot be undone.

They are withheld by default: absent from the tool descriptions and the operation enum, and refused with an explanation naming the single-record alternative if a client sends one anyway. Set IVEDAAI_ALLOW_COLLECTION_DELETE=true to permit them. IVEDAAI_READ_ONLY=true overrides that.

See SECURITY.md for the rest of the defaults, and for what leaves your deployment.

Using it

Every tool takes an operation and the arguments that operation needs:

{ "operation": "GET /api/cameras", "query": { "size": 20, "nameContains": "lobby" } }

• Usage guide — calling conventions and worked workflows: onboarding cameras, alert rules, analysis jobs, face and licence-plate watchlists.

• Tool reference — every tool, operation and parameter.

• Design and behaviour — why one tool per resource type, what the server does about partial updates the API silently discards, and the response format.

If a model needs the exact shape of a request body, ivedaai_get_schema returns it on demand rather than every tool description carrying it.

Requirements

Node 20.18.1 or newer, and an IvedaAI 10.0 deployment. The bundled API document is 10.0; point IVEDAAI_SWAGGER_PATH at your own if you run something else.

Contributing

See CONTRIBUTING.md. Upgrading the API document? npm run diff:spec -- --against <new-spec.json> reports what changed and, more usefully, whether anything this repo records now points at an operation that no longer exists.

License

MIT — see LICENSE.