Scratchpad

You set up and run a Scratchpad MCP v2 server to share and manage collaborative scratchpad content across Claude Code sub-agents. This MCP server provides workflow-scoped scratchpads, semantic block operations, smart search, and AI-assisted analysis, all accessible through a local stdio-based server that you start with a startup script.

How to use

You interact with the Scratchpad MCP server through an MCP client to create and manage workflows and scratchpads, tail or chop scratchpad content, perform smart searches, and run AI-based analyses. Workflows organize related scratchpads, and you can retrieve outlines, blocks, and context around specific sections to support structured collaboration. Use the startup script to ensure reliable path handling and proper extension loading.

Typical usage patterns include creating a workflow, adding scratchpads to that workflow, editing scratchpad content in multiple modes, and performing full-text or context-aware searches across scratchpads and workflows. You can tail or fetch specific line ranges with context, parse scratchpad outlines for navigation, and extract AI-driven insights from your data. All interactions assume the MCP server is running via the startup script to guarantee correct environment setup.

How to install

Prerequisites: you need Node.js 18.0.0 or newer and SQLite with automatic FT S5 support.

Step-by-step setup you can follow:

# Prerequisites
node -v
# Ensure Node.js 18+ is installed

# 1) Clone the project
git clone <repository-url>
cd scratchpad-mcp-v2

# 2) Install dependencies
npm install

# 3) Build and typecheck
npm run build
npm run typecheck

# 4) Make startup script executable
chmod +x start-mcp.sh

# 5) Start the MCP server (production mode)
./start-mcp.sh

Configuration and startup notes

Always start the server using the startup script to ensure correct path resolution and database handling. This script ensures cross-directory compatibility and proper loading of optional Chinese tokenization extensions. If you run the server directly with a path like dist/server.js, you may encounter path resolution and tokenizer issues.

Environment variables you may set before starting the server include the database path and AI API key:

export SCRATCHPAD_DB_PATH="./my-scratchpad.db"
export OPENAI_API_KEY="your-openai-api-key"
export SCRATCHPAD_DISABLED_TOOLS="get-scratchpad,get-scratchpad-outline"
./start-mcp.sh

Security and best practices

Use absolute paths for startup configurations when integrating with editors or Claude Code, and keep sensitive keys like the AI API key in environment variables rather than embedding them in code. Regularly update dependencies and run the test suite to catch regressions early.

Commit a project-level configuration for MCP clients to ensure consistent startup across teams. Validate that the startup script is executable and that the database path is accessible by the running process.

Troubleshooting notes

If the server fails to start, verify you are on Node 18+, that the startup script is executable, and that you are using an absolute path for the startup script when configuring MCP clients.

If Chinese tokenization features do not load, confirm that the startup script loaded the tokenizer extensions and that any required native libraries are present in the extensions directory.

If you see issues with tokenization or search results, ensure you are using the startup script (not dist/server.js) to preserve correct path handling and tokenizer initialization.

Notes on usage patterns and scope

The server provides a rich set of tools to manage workflows and scratchpads, including creating and listing workflows, retrieving and updating scratchpads, applying multi-mode edits, and performing full-text and context-aware searches across content.

Examples of common flows

Create a workflow, add scratchpads, and perform a multi-step edit sequence to refine notes and findings. Then retrieve an outline to navigate the scratchpad structure and tail content to fetch recent sections for review.

Available tools

create-workflow

Create a new workflow container to organize related scratchpads.

list-workflows

List all workflows with optional scope filters.

get-workflow

Retrieve a workflow by ID with optional scratchpad summaries.

get-latest-active-workflow

Fetch the most recently updated active workflow.

update-workflow-status

Activate or deactivate a workflow.

create-scratchpad

Create a scratchpad within a specific workflow.

get-scratchpad

Retrieve a scratchpad by ID with optional line ranges and context.

get-scratchpad-outline

Parse markdown headers in a scratchpad and return a structured outline.

append-scratchpad

Append content to an existing scratchpad.

tail-scratchpad

Tail or fetch full content, with block-based semantic extraction support.

chop-scratchpad

Remove content from the end of a scratchpad, supporting block-based removal.

update-scratchpad

Multi-mode editing for replace, insert, replace-lines, or append-section.

list-scratchpads

List scratchpads within a workflow with pagination and previews.

search-scratchpads

Full-text search across scratchpads with context-aware snippets and tokenization options.

search-scratchpad-content

Search within a single scratchpad using string or regex patterns with context.

search-workflows

Search workflows with weighted scoring across names, descriptions, and scratchpad content.

extract-workflow-info

AI-assisted extraction of structured information from workflows.