topview-mcp-server

MCP server exposing TopView.ai's video and image generation API as tools for Claude.

Setup

1. Copy .env.example to .env and fill in your credentials (Account icon > API Settings on topview.ai):

TOPVIEW_API_KEY=...
TOPVIEW_UID=...

2. Install and build:

npm install
npm run build

Tools

Uploading

All three return a fileId that the generation tools consume. Which one to use depends on where the file is and where this server runs:

• topview_upload_base64 — use this by default. The client sends the file contents, so it works regardless of where the server runs. This is the one that makes drag-and-drop attachments work against a hosted deployment. Practical up to ~10 MB (base64 inflates payloads ~33%, and MCP clients cap message size).
• topview_upload_url — the server downloads a public http(s) URL, then uploads it. Best for large files, or media that already lives on a CDN. URLs resolving to private, loopback, or link-local addresses are rejected.
• topview_upload_file — reads a path on the server's own filesystem. Only works under the stdio transport, where server and client share a machine. Under the hosted HTTP transport the client's paths do not exist on the server and every call fails; use one of the two above.

Generation

• topview_text_to_video_submit / topview_text_to_video_query
• topview_image_to_video_submit / topview_image_to_video_query
• topview_text_to_image_submit / topview_text_to_image_query
• topview_image_edit_submit / topview_image_edit_query

Submit tools accept waitForCompletion (default true) to poll internally (every ~4s, up to 5 minutes) and return the finished asset, or false to return immediately with a taskId for manual polling via the matching query tool.

Registering with Claude Code

claude mcp add topview -- node "G:/07_ClaudeCode/topview-mcp-server/dist/index.js"

Registering with Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config), under mcpServers:

"topview": {
  "command": "node",
  "args": ["G:/07_ClaudeCode/topview-mcp-server/dist/index.js"]
}

Restart Claude Desktop completely (quit, not just close the window) for it to load.

Using it from Cowork (remote/hosted mode)

Cowork sessions run in the cloud and can't launch a local process on your machine — they can only reach an MCP server over the network. This repo ships a second entry point, src/httpServer.ts, that exposes the exact same tools over Streamable HTTP so it can be hosted and added as a custom connector.

1. Deploy this repo to any Node host (Render, Railway, Fly.io, etc.):
   • Build command: npm install && npm run build
   • Start command: npm run start:http
   • Environment variables to set on the host: TOPVIEW_API_KEY, TOPVIEW_UID, and TOPVIEW_MCP_ACCESS_TOKEN (a long random secret — required, otherwise anyone who finds the URL can spend your TopView credits). The host usually sets PORT automatically.
2. Once deployed you'll have a public URL, e.g. https://topview-mcp.onrender.com.
3. In Claude, go to Settings > Connectors > Add a custom connector and fill in:
   • Nom: topview
   • URL du serveur MCP distant: https://topview-mcp.onrender.com/mcp?token=YOUR_SECRET (the ?token= must match TOPVIEW_MCP_ACCESS_TOKEN; leave the OAuth fields empty)
4. It will then be available in every Cowork session, not just one project folder.

GET /healthz returns ok once the server is up, useful for checking a deploy succeeded.

Uploading files in hosted mode

A hosted server has no access to your machine's filesystem, so topview_upload_file cannot work there — a path like C:\Users\you\image.png simply does not exist inside the container, and no amount of path rewriting changes that. Use topview_upload_base64 (client sends the bytes) or topview_upload_url (server fetches a public URL) instead. Both are transport-agnostic and work in local mode too.