@bilinote/mcp-server

MCP server for BiliNote Pro — generate AI study notes from videos using the BiliNote public API. Works with online URLs (Bilibili, YouTube, Douyin, Kuaishou) and local video files on your machine.

What it does

Exposes five MCP tools to any MCP-compatible agent (Claude Code, Codex, Cursor, etc.):

| Tool | Description | |------|-------------| | generate_note | Generate a note from an online URL (videoUrl) or a local video file (filePath); optionally file it into a collection via collectionId. Blocks until the note is ready, returns markdown. Takes minutes and costs credits. | | list_models | List available AI models and their credit cost per generation. | | get_task | Check (or resume) a generation task by taskId. | | get_note | Fetch a completed note by noteId. | | list_notes | List notes in the account library (paginated). | | get_account | Remaining credits (balance), total earned/consumed, VIP status & plan, and this key's rate limit / spend cap. | | list_collections | List the account's note collections (id, name, note count). | | get_collection | A collection's contents — its info plus the notes inside it. | | create_collection | Create a collection; returns its collectionId to pass to generate_note. |

Prerequisites

1. A BiliNote Pro account with credits.
2. An API key — create one in Settings → API / 开发者 in the BiliNote web app.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BILINOTE_API_KEY | Yes | — | Your bn_live_… API key | | BILINOTE_API_BASE | No | https://www.bilinote.net/api | Base URL of the BiliNote API |

Note: The default BILINOTE_API_BASE targets the hosted BiliNote Pro API. For local development against your own backend, set BILINOTE_API_BASE=http://localhost:8080/api. For a self-hosted instance, set it to your domain + /api.

Agent configuration

Claude Code

One-liner install:

claude mcp add bilinote -e BILINOTE_API_KEY=bn_live_YOUR_KEY_HERE -- npx -y @bilinote/mcp-server

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "bilinote": {
      "command": "npx",
      "args": ["-y", "@bilinote/mcp-server"],
      "env": {
        "BILINOTE_API_KEY": "bn_live_YOUR_KEY_HERE"
      }
    }
  }
}

Codex

Add to your Codex configuration under mcpServers:

{
  "mcpServers": {
    "bilinote": {
      "command": "npx",
      "args": ["-y", "@bilinote/mcp-server"],
      "env": {
        "BILINOTE_API_KEY": "bn_live_YOUR_KEY_HERE"
      }
    }
  }
}

Cursor

In Cursor's MCP settings (.cursor/mcp.json or the Cursor settings UI), add:

{
  "mcpServers": {
    "bilinote": {
      "command": "npx",
      "args": ["-y", "@bilinote/mcp-server"],
      "env": {
        "BILINOTE_API_KEY": "bn_live_YOUR_KEY_HERE"
      }
    }
  }
}

Usage notes

• generate_note costs credits from your BiliNote account — each generation deducts from your wallet according to the model's cost.
• Generation typically takes 1–5 minutes depending on video length and model. The tool polls internally and returns the note markdown when complete.
• If generation exceeds maxWaitSeconds (default 600 s / 10 min), the tool returns a taskId string. Use get_task with that ID to resume.
• If generation fails, generate_note returns an error with the failure reason.

Local video files

Pass filePath (an absolute path to a video file on the machine running the MCP server) instead of videoUrl:

// generate_note arguments
{ "filePath": "/Users/me/clips/lecture.mp4", "model": "gpt-4o" }

The server uploads the file to BiliNote in 5 MB chunks with resumable upload, then runs generation as platform=LOCAL. If the upload is interrupted (network drop, process exit), the next call resumes from where it left off — it tracks progress in ~/.bilinote/uploads.json (keyed by path + size + mtime) and only re-sends the missing chunks. Provide either videoUrl or filePath, not both.

Local development

git clone <this-repo>
cd integrations/mcp-server
npm install
npm run build
BILINOTE_API_KEY=bn_live_... node dist/index.js