scrapbox-cosense-mcp

日本語ドキュメント / Japanese

Overview

MCP server for Cosense (formerly Scrapbox).

Tool	Description	Auth Required
get_page	Get page content, metadata, and links	For private projects
list_pages	Browse pages with sorting and pagination (max 1000)	For private projects
search_pages	Full-text search with keyword highlighting (max 100 results)	For private projects
create_page	Create a page via WebSocket API with Markdown/Scrapbox body	Yes
get_page_url	Generate direct URL for a page	No
insert_lines	Insert text after a specified line in a page	Yes
get_smart_context	Get a page and its linked pages (1-hop/2-hop) in AI-optimized format	Yes

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

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:

Client	Config File
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%/Claude/claude_desktop_config.json
Cursor	.cursor/mcp.json (project root)
Windsurf	~/.codeium/windsurf/mcp_config.json

{
  "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

Variable	Description
COSENSE_PROJECT_NAME	Your Scrapbox/Cosense project name
COSENSE_SID	Session ID (connect.sid cookie) for private projects — How to get it

Optional

Variable	Default	Description
API_DOMAIN	scrapbox.io	API domain
SERVICE_LABEL	cosense (scrapbox)	Display name in tool descriptions
COSENSE_PAGE_LIMIT	100	Initial page fetch limit (1–1000)
COSENSE_SORT_METHOD	updated	Initial sort: updated, created, accessed, linked, views, title
COSENSE_TOOL_SUFFIX	—	Tool name suffix for multiple instances (e.g. main → get_page_main)
COSENSE_CONVERT_NUMBERED_LISTS	false	Convert numbered lists to bullet lists in Markdown conversion
COSENSE_EXCLUDE_PINNED	false	Exclude pinned pages from initial resource list

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 url "Page Title"

Flag	Description
--compact	Token-efficient compact output (recommended for AI agents)
--project=NAME	Override project name
--json	Output as JSON
--help	Show help (supports <command> --help for details)

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

Command	Description
npm run build	Build (TypeScript → JavaScript)
npm run watch	Auto-rebuild during development
npm test	Run test suite
npm run lint	Run ESLint
npm run inspector	Debug with MCP Inspector

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

---