PageSpace MCP Server

A Model Context Protocol (MCP) server that enables Claude Code and Claude Desktop to directly read, edit, create, manage, and organize your PageSpace documents with full CRUD operations and line-level precision.

Quick Start

1. Set up MCP tokens in your PageSpace instance
2. Configure Claude Desktop/Code with your tokens (no installation needed!)
3. Start editing your PageSpace documents with Claude!

Features

• 32 Powerful Tools: Complete workspace management with drive, page, search, batch, and AI agent operations
• Full CRUD Operations: Create, read, update, and delete pages of all types
• Page Management: Move, reorder, trash, and restore pages with hierarchy support
• Line-based editing: Replace, insert, or delete specific lines with precision
• Multi-page types: Support for FOLDER, DOCUMENT, CHANNEL, AI_CHAT, CANVAS
• Advanced Search: Regex and glob pattern search across drives and pages
• Batch Operations: Bulk move, rename, delete, and update multiple pages
• AI Agent Integration: Create, configure, and communicate with AI agents
• Trash system: Safe soft-delete with restore capabilities
• HTML-aware: Automatic Prettier formatting
• Secure: User-specific authentication tokens
• Real-time sync: Changes appear immediately in the web editor

Available Tools

📁 Core Drive & Page Operations (9 tools)

• list_drives - List all available workspaces/drives with access permissions
• list_pages - Explore page tree structure within a specific drive
• read_page - Read any document content with line numbers and metadata
• create_page - Create new pages (FOLDER, DOCUMENT, CHANNEL, AI_CHAT, CANVAS)
• rename_page - Rename existing pages with validation
• trash_page - Move single page to trash (soft delete)
• move_page - Move or reorder pages within drive hierarchy
• list_trash - List all trashed pages in a drive
• read_current_page - Read the current page context

✏️ Content Editing (7 tools)

• replace_lines - Replace specific line(s) with new content (1-based indexing)
• insert_lines - Insert new content at specific line position
• delete_lines - Delete specific line(s) or line ranges
• append_to_page - Add content to the end of a page
• prepend_to_page - Add content to the beginning of a page
• trash_page_with_children - Move page and all children to trash recursively
• restore_page - Restore pages from trash

🚀 Drive Management (4 tools)

• create_drive - Create new workspaces/drives
• rename_drive - Rename existing drives (owner only)
• trash_drive - Move entire drive to trash (with safety confirmation)
• restore_drive - Restore trashed drives

🔍 Search & Discovery (3 tools)

• regex_search - Search page content using regular expressions
• glob_search - Find pages using glob patterns for titles/paths
• multi_drive_search - Search across multiple drives simultaneously

⚡ Batch Operations (5 tools)

• bulk_move_pages - Move multiple pages in one atomic operation
• bulk_rename_pages - Rename multiple pages using patterns or templates
• bulk_delete_pages - Delete multiple pages atomically
• bulk_update_content - Update content in multiple pages at once
• create_folder_structure - Create complex nested folder structures

🤖 AI Agent System (5 tools)

• create_agent - Create new AI agents with custom system prompts and tools
• update_agent_config - Update agent configuration, prompts, and enabled tools
• list_agents - List all AI agents in a specific drive
• multi_drive_list_agents - List AI agents across all accessible drives
• ask_agent - Consult AI agents for specialized assistance (supports tool usage)

Setup Instructions

1. Generate an MCP Token

1. Start your PageSpace application
2. Navigate to Dashboard > Settings > MCP Connection (or /dashboard/settings/mcp)
3. Click Create New Token to generate a new MCP token
4. Give your token a descriptive name (e.g., "Claude Desktop", "Development")
5. Copy and save the token immediately - it's only shown once for security

2. Configure Claude Desktop

Add this to your Claude Desktop MCP configuration file:

For PageSpace Beta (most common):

{
  "mcpServers": {
    "pagespace": {
      "command": "npx",
      "args": [
        "-y",
        "pagespace-mcp@latest"
      ],
      "env": {
        "PAGESPACE_API_URL": "https://beta.pagespace.ai",
        "PAGESPACE_AUTH_TOKEN": "<YOUR_PAGESPACE_MCP_TOKEN_HERE>"
      }
    }
  }
}

For self-hosted PageSpace:

{
  "mcpServers": {
    "pagespace": {
      "command": "npx",
      "args": [
        "-y",
        "pagespace-mcp@latest"
      ],
      "env": {
        "PAGESPACE_API_URL": "https://your-pagespace-domain.com",
        "PAGESPACE_AUTH_TOKEN": "<YOUR_PAGESPACE_MCP_TOKEN_HERE>"
      }
    }
  }
}

3. Test the Connection

Restart Claude Desktop and try:

"Show me my drives"

Claude should list your available drives, then you can:

"Show me the page tree in [drive-name]"
"Read the [document-name] document"

Claude will guide you through the workflow: drives → page tree → documents → editing!

Usage Examples

Getting Started

"Show me my drives" "Show me the page tree in my-drive" (use driveSlug and driveId from list_drives) "Read the document [page-id]" (use pageId from list_pages)

Line Replacement

"Replace line 15 in [page-id] with a new heading: <h2>New Section</h2>" (use pageId from list_pages)

Content Addition

"Add a new paragraph at the end of [page-id] about project conclusions" (use pageId from list_pages)

Precise Editing

"Delete lines 8-10 from [page-id] and replace them with a code block showing the API example" (use pageId from list_pages)

Page Management

"Create a new folder called 'Meeting Notes' in drive [drive-id]" "Create a document called 'Project Plan' under parent [parent-id] with some initial content" "Rename page [page-id] to 'Q4 Project Plan'" "Move page [page-id] to be under parent [parent-id] at position 2"

Trash and Restore

"Move page [page-id] to trash" (single page only) "Trash page [page-id] with all children" (recursive) "Show me what's in the trash for drive [drive-id]" "Restore page [page-id] from trash"

Advanced Operations

"Create an AI chat page called 'Brainstorming' in drive [drive-id]" "Search for all pages containing 'TODO' using regex in drive [drive-id]" "Bulk rename all pages starting with 'Draft' to add 'Final' prefix" "Create a folder structure for a new project with docs, meetings, and resources folders"

AI Agent Operations

"Create an AI agent called 'Code Reviewer' with tools for reading and analyzing pages" "List all AI agents across my workspaces" "Ask the 'Documentation Writer' agent to help improve this page"

Workflow

The typical workflow is: drives → page tree → documents → editing/management.

For content editing: list_drives → list_pages → read_page (with pageId) → replace_lines/insert_lines/delete_lines (with same pageId) For page management: list_drives → list_pages → create/rename/move/trash pages (using IDs) → list_pages to verify

Note: The system uses IDs for operations. When you use list_pages, you'll see both the path (for easy reading) and the ID (for operations).

Claude will guide you through each step!

Security Notes

• Each MCP token is scoped to your specific user account
• Tokens can be revoked at any time from the web interface
• The server only accesses your documents, not other users'
• All changes go through the same validation as the web editor

Development

To run the MCP server in development mode:

pnpm run dev

This enables file watching for automatic restarts during development.

Troubleshooting

Authentication Errors

• Verify your MCP token is correct and hasn't been revoked
• Check that PAGESPACE_AUTH_TOKEN is set in your MCP configuration

Connection Issues

• Ensure your PageSpace app is running on the specified URL
• Check that the API URL in the MCP config matches your app's URL

Line Number Issues

• Line numbers are 1-based (first line is line 1)
• After operations, Prettier may reformat and change line numbers
• Always read the document first to see current line numbers

API Reference

The MCP server communicates with these PageSpace endpoints:

• /api/mcp/drives - Drive discovery and listing
• /api/mcp/documents - Document operations (GET for reading, POST for write operations)
• /api/mcp/detect-paths - Path validation and normalization
• /api/auth/mcp-tokens - MCP token management (GET to list, POST to create)
• /api/auth/mcp-tokens/[tokenId] - Revoke MCP token (DELETE)

Requirements

• Node.js: >= 18.0.0
• PageSpace: Any version with MCP support
• Claude Desktop or Claude Code with MCP enabled

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

Support

• 💬 Discord: Join our Discord for support questions
• 📖 Documentation: PageSpace Docs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the PageSpace Team