Scrapbox Cosense

You can run a specialized MCP server to interact with Cosense and Scrapbox pages. This server provides tools to fetch pages, browse and search content, create pages, and generate direct URLs, all wired to per-project configurations and optional multi-project setups for private data access. Implementing these endpoints lets you automate content workflows and empower AI assistants to work with Scrapbox-based knowledge bases.

How to use

You interact with the MCP server through an MCP client. The server exposes tools that let you get page content, list pages with flexible sorting, search within pages, create new pages, generate page URLs, and insert text after a specific line in a page. You can target a specific Scrapbox Cosense project by supplying a project name when calling the tools. If you do not supply a project name, the server will use the default project configured in your environment.

How to install

Prerequisites: Node.js and npm must be installed on your system. You will also need a Cosense Scrapbox project and, for private projects, a valid COSENSE_SID cookie value.

Choose one of the installation methods below and follow the steps exactly.

Option A: Desktop Extension (.mcpb) — Easiest, No Terminal Required

Option B: Claude Code (CLI) to run from the command line

Option C: Claude Desktop (JSON Configuration) for persistent setup

Option D: Other MCP Clients (Cursor, Windsurf, etc.)

Option E: Build from Source

Configuration and multi-project setup

You can operate across multiple Cosmosense Scrapbox projects by configuring separate MCP server instances or by using a single server with an optional projectName parameter. The multi-server approach is recommended when you handle distinct private projects with different credentials.

Below is an example configuration for running two MCP server instances, each targeting a different project. The first instance handles the main project, and the second handles a team project. Each instance uses a unique tool suffix to create distinct tool names.

{
  "mcpServers": {
    "main-scrapbox": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "main-project",        
        "COSENSE_SID": "s:main_sid_here...",           
        "COSENSE_TOOL_SUFFIX": "main",                 
        "SERVICE_LABEL": "Main Scrapbox"               
      }
    },
    "team-cosense": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "team-workspace",      
        "COSENSE_SID": "s:team_sid_here...",           
        "COSENSE_TOOL_SUFFIX": "team",                 
        "SERVICE_LABEL": "Team Cosense"                
      }
    }
  }
}

Security and credentials

For private projects, you must supply a COSENSE_SID value that authenticates access to the project. Treat this value with care and never share it publicly. If the SID expires or becomes invalid, obtain a new cookie as described in the SID retrieval steps and update your environment accordingly.

Usage examples

Once configured, you can instruct the MCP client to use the available tools with the appropriate project context. For example, you can fetch the content of a specific page, list recently updated pages, search for content containing a keyword, create a new page in a chosen project, or obtain a direct URL for a page.

Development and testing notes

Development follows a typical Node.js workflow with dependencies installation, a build step, and tests. You can also run linting to ensure code quality. When debugging, you can use the MCP Inspector to inspect runtime behavior in a browser.

Available tools

get_page

Fetches the content of a Scrapbox cosense page, returning content, metadata, links, and editor information for a given page title and optional project name.

list_pages

Lists pages with flexible sorting and pagination to discover pages by recency, popularity, or alphabetically, returning page metadata and the first five lines of content with a maximum of 1000 pages per request.

search_pages

Searches within pages using keywords or phrases with support for basic/AND/exclude/exact phrase searches, returning matching pages with highlighted terms and content snippets (max 100 results).

create_page

Creates a new page in a specified project via WebSocket, converting Markdown to Scrapbox format and optionally converting numbered lists to bullets; requires COSENSE_SID for authentication.

get_page_url

Generates a direct URL for a specified page in a project.

insert_lines

Inserts text after a specified line in a page, or appends to the end if the target line is not found.