scrapbox-cosense-mcp

English | 日本語

English

MCP server for cosense/scrapbox.

Features

• get_page
  • Get page content from cosense/Scrapbox
    • Input: Page title
    • Output: Page content, metadata, links, and editor information
• list_pages
  • Get a list of pages in the project (max 1000 pages)
    • Output: List of page titles in the project
• search_pages
  • Full-text search across all pages in the project (max 100 pages)
    • Supports basic search, AND search, OR search, and NOT search
    • Output: List of page titles in search results
• create_pages
  • Generate page URLs
    • Input: Page title and optional body text
    • Output: URL that can be opened in a browser

Development

Install dependencies:

npm install

Build the server:

npm run build

Auto-rebuild during development:

npm run watch

Installation

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

To use with Claude Desktop, add the server configuration as follows:

For MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
For Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scrapbox-cosense-mcp": {
      "command": "npx",
      "args": ["github:worldnine/scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "your_project_name",
        "COSENSE_SID": "your_sid", // Required for private projects
        "COSENSE_PAGE_LIMIT": "25", // Optional (default: 100)
        "COSENSE_SORT_METHOD": "created", // Optional (default: "updated")
        "SERVICE_LABEL": "scrapbox(cosense)" // Optional (default: "cosense(scrapbox)")
      }
    }
  }
}

Environment Variables

This server uses the following environment variables:

Required Environment Variables

• COSENSE_PROJECT_NAME: Project name
• COSENSE_SID: Session ID for Scrapbox/Cosense authentication (required for private projects)

Optional Environment Variables

• API_DOMAIN: API domain (default: "scrapbox.io")
• SERVICE_LABEL: Service identifier (default: "cosense (scrapbox)")
• COSENSE_PAGE_LIMIT: Initial page fetch limit (1-1000, default: 100)
• COSENSE_SORT_METHOD: Initial page fetch order (updated/created/accessed/linked/views/title, default: updated)

Environment Variable Behavior

• COSENSE_PROJECT_NAME: Required environment variable. Server will exit with an error if not set.
• COSENSE_SID: Required for accessing private projects. If not set, only public projects are accessible.
• API_DOMAIN:
  • Uses "scrapbox.io" if not set
  • While unverified with domains other than "scrapbox.io" in the author's environment, this option exists in case some environments require "cosen.se"
• COSENSE_PAGE_LIMIT:
  • Uses 100 if not set
  • Uses 100 if value is invalid (non-numeric or out of range)
  • Valid range: 1-1000
• COSENSE_SORT_METHOD:
  • Uses 'updated' if not set
  • Uses 'updated' if value is invalid
  • Does not affect list_pages tool behavior (only used for initial resource fetch)

Debugging

Since MCP servers communicate via stdio, debugging can be challenging. Using MCP Inspector is recommended. You can run it with:

npm run inspector

The Inspector provides a URL to access debugging tools in the browser.

日本語

cosense/scrapbox 用のMCPサーバーです。

機能

• get_page

  • cosense/Scrapbox からページ内容を取得
    • 入力: ページタイトル
    • 出力: ページ内容、メタデータ、リンク、および編集者情報

• list_pages

  • プロジェクト内のページ一覧を取得（最大1000ページ）
    • 出力: プロジェクト内のページタイトルの一覧

• search_pages

  • プロジェクト内の全ページで全文検索（最大100ページ）
    • 基本検索、AND検索、OR検索、NOT検索をサポート
    • 出力: 検索結果のページタイトル一覧

• create_pages

  • ページURLを生成
    • 入力: ページタイトルとオプションの本文
    • 出力: ブラウザで開けるURL

• get_page

  • 从cosense/Scrapbox获取页面内容
    • 输入: 页面标题
    • 输出: 页面内容、元数据、链接、编辑者信息

• list_pages

  • 获取项目内的页面列表（最多1000个）
    • 输出: 项目内页面标题列表

• search_pages

  • 在项目内所有页面中进行全文搜索（最多100个结果）
    • 支持基本搜索、AND搜索、OR搜索、NOT搜索
    • 输出: 搜索结果的页面标题列表

• create_pages

  • 生成页面的URL
    • 输入: 页面标题和可选的正文文本
    • 输出: 可在浏览器中打开的URL

开发方法

安装依赖项：

npm install

构建服务器：

npm run build

开发时自动重建：

npm run watch

安装方法

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

要在Claude Desktop中使用，请按如下方式添加服务器设置：

对于MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
对于Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scrapbox-cosense-mcp": {
      "command": "npx",
      "args": ["github:worldnine/scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "your_project_name",
        "COSENSE_SID": "your_sid", // プライベートプロジェクトの場合は必須
        "COSENSE_PAGE_LIMIT": "25", // オプション（デフォルト: 100）
        "COSENSE_SORT_METHOD": "created", // オプション（デフォルト: "updated"）
        "SERVICE_LABEL": "scrapbox(cosense)" // オプション（デフォルト: "cosense(scrapbox)"）
      }
    }
  }
}

环境变量

此服务器使用以下环境变量：

必需的环境变量

• COSENSE_PROJECT_NAME: 项目名称
• COSENSE_SID: Scrapbox/Cosense的身份验证会话ID（私有项目必需）

可选的环境变量

• API_DOMAIN: API域（默认: "scrapbox.io"）
• SERVICE_LABEL: 服务标识名（默认: "cosense (scrapbox)"）
• COSENSE_PAGE_LIMIT: 初始获取时的页面数量（1-1000，默认: 100）
• COSENSE_SORT_METHOD: 初始获取时的获取页面顺序（updated/created/accessed/linked/views/title，默认: updated）

关于环境变量的行为

• COSENSE_PROJECT_NAME: 必需的环境变量。未设置时，服务器将在启动时因错误而退出。
• COSENSE_SID: 访问私有项目所需。未设置时，只能访问公共项目。
• API_DOMAIN:
  • 未设置时使用"scrapbox.io"
  • 尽管作者环境中除"scrapbox.io"外的值未经验证，但提供此选项以防存在仅支持"cosen.se"的环境。
• COSENSE_PAGE_LIMIT:
  • 未设置时使用100
  • 对于无效值（非数字或超出范围），将使用100
  • 有效范围: 1-1000
• COSENSE_SORT_METHOD:
  • 未设置时使用'updated'
  • 对于无效值，将使用'updated'
  • 不影响list_pages工具的行为（仅在初始资源获取时使用）

调试方法

由于MCP服务器通过stdio通信，调试可能较为困难。推荐使用MCP Inspector。可以通过以下命令执行：

npm run inspector

Inspector提供了可以在浏览器中访问调试工具的URL。