Scrapbox/CoSense

★ 46

from worldnine

A server for the Scrapbox/CoSense platform to retrieve, list, search, and create pages.

🔥🔥🔥✓ VerifiedFreeAdvanced setup

#automation #scraping #git

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.

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

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

License

MIT

Copy & paste — that's it

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

Before it works, you'll need: COSENSE_PROJECT_NAMECOSENSE_SID

Quick Start

Desktop Extension (.mcpb) — Easiest

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

Claude Code Plugin

Add the marketplace:

/plugin marketplace add worldnine/scrapbox-cosense-mcp

Install the plugin:
```
/plugin install scrapbox-cosense@worldnine-scrapbox-cosense-mcp
```
Installs globally by default. Use --scope project or --scope local for other scopes.
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)

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)