ivedaai-mcp-server

                         . . . SIGNAL // LOCKED . . .

                         [CAM]        [ALERT]        [RULE]
                            \            |            /
                             \           |           /
                    [FACE] ----\------ [ MCP ] ------/---- [LPR]
                               \         |         /
                                \        |        /
                               [SEARCH]  |  [ANALYSIS]
                                         |

██╗██╗   ██╗███████╗██████╗  █████╗  █████╗ ██╗    ███╗   ███╗ ██████╗██████╗ 
██║██║   ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██║    ████╗ ████║██╔════╝██╔══██╗
██║██║   ██║█████╗  ██║  ██║███████║███████║██║    ██╔████╔██║██║     ██████╔╝
██║╚██╗ ██╔╝██╔══╝  ██║  ██║██╔══██║██╔══██║██║    ██║╚██╔╝██║██║     ██╔═══╝ 
██║ ╚████╔╝ ███████╗██████╔╝██║  ██║██║  ██║██║    ██║ ╚═╝ ██║╚██████╗██║     
╚═╝  ╚═══╝  ╚══════╝╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝    ╚═╝     ╚═╝ ╚═════╝╚═╝     

                     |                                       |
                     |   VIDEO INTELLIGENCE <-> AI TOOLS     |
                     +-------------------+-------------------+
                                         |
                               316 API OPERATIONS
                                  63 MCP TOOLS

                           :: DECODE // OBSERVE // ACT ::

ivedaai-mcp-server

An MCP server for the IvedaAI video analytics API. Point a client that launches local MCPprocesses, such as Claude Desktop or Claude Code, at your IvedaAI deployment and drive it in naturallanguage: search footage, manage cameras and alert rules, run analysis jobs, work with face andlicence-plate watchlists.

Transports: the default command uses stdio. An authenticated HTTP previewis available through node dist/http.js /protected/path/customer.json: read-only by default, with optionaladministrator-enabled actions and separate user consent to changes. It uses a fixedcustomer server and isolated user accounts. Customers can use their existing IvedaAI login;no separate sign-in vendor is required. An HTTPS reverse proxy and approved AI-client callbackconfiguration are needed; real browser-client/TLS validation is still outstanding.See browser connection requirements for deployment options.Pilot teammates can use the team quickstart; operators should startwith the per-user pilot route.IVEDAAI_BASE_URL is the upstream application's address, not an MCP connection URL.

The bundled API defines 316 operations. By default, 295 are exposed through 63 resource tools,plus three helper tools; 21 collection-wide DELETEs are withheld. See why.

Quickstart

The npm package was not yet available when checked on 2026-09-04. Until the initial release ispublished, clone this repository, run npm ci and npm run build, then configure the client with command: "node"and args: ["/absolute/path/to/ivedaAI-mcp-server/dist/index.js"].

After publication, this configuration lets npx fetch the package:

{
  "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 theconfiguration reference; --version prints the version.

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": "…" }

Mutating operations are withheld from the tool list. Reads include GETs and the three verifiedquery-only POSTs for alert statistics, search, and latest alerts. The two write-oriented conveniencetools are withheld too.

Configuration

Only the first three are required.

Copy .env.example if you prefer a file. The server does not load .env automatically:export its values into the environment or run a local build with node --env-file=.env dist/index.js.

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 ratelimited: a client that starts a fresh process per request will hit it.

Destructive operations

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

They are withheld by default: absent from the tool descriptions and the operation enum, andrefused with an explanation naming the single-record alternative if a client sends one anyway. SetIVEDAAI_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 doesabout 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 ratherthan every tool description carrying it.

Requirements

Node 22.16.0+ in the 22.x line, or Node 24+, and an IvedaAI 10.0 deployment. Use the latest patched Node 22 or 24 LTSrelease in production; Node 20 is no longer supported. The bundled API document is 10.0; pointIVEDAAI_SWAGGER_PATH at your own if you run something else.

Earlier Node 22 versions and Node 23 are unsupported because request deadlines depend on theAbortSignal.any() timeout fix included in Node 22.16.0.CI covers the minimum supported Node 22 version and Node 24.

Production operation

For stdio, each MCP client starts its own process and communicates over stdin/stdout; that entrypoint has no HTTP listener. The separate HTTP preview uses existing IvedaAI loginbehind an operator-managed HTTPS proxy. Neither mode provisions a database, container or separatehealth endpoint. Successful MCP initialization and a small authorized read provide integration checks.

Use HTTPS with a valid certificate, a dedicated IvedaAI account with only the required applicationpermissions, and read-only mode for monitoring. The server adds read-only, collection-delete,lossy-update, and upload restrictions; record-level authorization remains IvedaAI's responsibility.Treat client configuration as a secret and approve an upload directory only when uploads are needed.After release, pin the approved npm version in your client configuration for reproducible installs.

Outbound redirects are refused. Configure the final deployment origin directly. Incomplete ormalformed JSON is withheld when redaction is enabled, since its credential fields cannot bereliably masked. Reduce the page size or narrow the filter; SSE reads retain only complete,redacted events. Cancellation and client disconnect stop further API work, but cannot undo anapplication write already received. Inspect uncertain writes before retrying.

Contributing

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

License

MIT — see LICENSE.