scrapbox-cosense-mcp

日本語ドキュメント / Japanese

Overview

MCP server for Cosense (formerly Scrapbox).

create_page, insert_lines, and edit_lines support a format parameter ("markdown" or "scrapbox") to control content conversion.

edit_lines replaces only the first matching line by default. Set matchAll: true to replace every occurrence. The default is deliberately conservative: a line such as a bullet marker or a blank line can repeat many times in a page, and replacing all of them at once is rarely what the caller intended.

delete_page is opt-in

delete_page is not registered unless COSENSE_ENABLE_DELETE=true is set. Without it the tool does not appear in the tool list at all, so an agent cannot call it even by mistake. This server is often added to a shared MCP configuration, so deletion is exposed only to those who deliberately turn it on.

Deleting a page empties every one of its lines, and Cosense removes a page once all of its lines are empty. There is no undo. Two further guards are built in:

• The page must already exist. A missing page returns an error rather than a silent success. (The REST API returns a title line even for a page that was never created, so the check looks at persistent, the same way create_page does.)
• dryRun: true reports how many lines would be removed and shows the first five of them, without touching the page.

When you run several instances of this server for different projects, set the variable on each instance that should be allowed to delete:

{
  "mcpServers": {
    "cosense-notes": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "notes",
        "COSENSE_SID": "s:your-session-id",
        "COSENSE_TOOL_SUFFIX": "notes",
        "COSENSE_ENABLE_DELETE": "true"
      }
    },
    "cosense-archive": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "archive",
        "COSENSE_SID": "s:your-session-id",
        "COSENSE_TOOL_SUFFIX": "archive"
      }
    }
  }
}

Here the notes instance exposes delete_page_notes, while the archive instance exposes no deletion tool at all.

Note that insert_lines and edit_lines behave differently when the target line is absent. insert_lines appends to the end of the page, because "add this text somewhere" still has a reasonable outcome. edit_lines returns an error and leaves the page untouched, because "replace this specific line" has no meaningful fallback — appending the replacement would silently produce a page the caller never asked for.

Quick Start

Desktop Extension (.mcpb) — Easiest

1. Download scrapbox-cosense-mcp.mcpb from GitHub Releases
2. Double-click — Claude Desktop opens an install dialog
3. Enter your project name (and Session ID for private projects)

Claude Code Plugin

1. Add the marketplace:

   /plugin marketplace add worldnine/scrapbox-cosense-mcp
   

2. Install the plugin:

   /plugin install scrapbox-cosense@worldnine-scrapbox-cosense-mcp
   

   Installs globally by default. Use --scope project or --scope local for other scopes.
3. Set environment variables in your settings file:

   {
     "env": {
       "COSENSE_PROJECT_NAME": "your_project_name",
       "COSENSE_SID": "your_sid"
     }
   }
   

   File	Scope
   ~/.claude/settings.json	All projects (global)
   .claude/settings.local.json	This project only (gitignored)

The plugin includes MCP server configuration and a /cosense skill for CLI operations.

Claude Code (Manual MCP Setup)

If you prefer manual configuration over the plugin:

claude mcp add scrapbox-cosense-mcp \
  -e COSENSE_PROJECT_NAME=your_project \
  -e COSENSE_SID=your_sid \
  -- npx -y scrapbox-cosense-mcp

Claude Desktop / Other MCP Clients

Add to your config file:

{
  "mcpServers": {
    "scrapbox-cosense-mcp": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "your_project_name",
        "COSENSE_SID": "your_sid"
      }
    }
  }
}

Build from Source

git clone https://github.com/worldnine/scrapbox-cosense-mcp.git
cd scrapbox-cosense-mcp
npm install && npm run build

Configuration

Required

Optional

CLI Usage

The same binary also works as a standalone CLI:

scrapbox-cosense-mcp get "Page Title"
scrapbox-cosense-mcp search "keyword"
scrapbox-cosense-mcp list --sort=updated --limit=20
scrapbox-cosense-mcp create "New Page" --body="Markdown content"
scrapbox-cosense-mcp insert "Page" --after="target line" --text="new text"
scrapbox-cosense-mcp edit "Page" --target="old line" --text="new text"
scrapbox-cosense-mcp delete "Page" --dry-run   # needs COSENSE_ENABLE_DELETE=true
scrapbox-cosense-mcp url "Page Title"

Multiple Projects

All tools accept an optional projectName parameter to target a different project from a single server. For multiple private projects with different credentials, run separate server instances with COSENSE_TOOL_SUFFIX.

See docs/multiple-projects.md for detailed configuration examples.

Development

Contributing

1. Create a feature branch from main
2. Add tests for your changes
3. Run npm run lint && npm test
4. Create a pull request — CI runs automatically

License

MIT