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.

Installation

npm install -g pagespace-mcp

Or using pnpm:

pnpm add -g pagespace-mcp

Quick Start

1. Install the package globally
2. Set up MCP tokens in your PageSpace instance
3. Configure Claude Desktop/Code with your tokens
4. Start editing your PageSpace documents with Claude!

Features

• 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
• 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

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 local development:

{
  "mcpServers": {
    "pagespace": {
      "command": "<REPLACE_WITH_NODE_PATH>",
      "args": [
        "<REPLACE_WITH_NPM_GLOBAL_PATH>/pagespace-mcp/index.js"
      ],
      "env": {
        "PAGESPACE_API_URL": "https://beta.pagespace.ai",
        "PAGESPACE_AUTH_TOKEN": "<YOUR_PAGESPACE_MCP_TOKEN_HERE>"
      }
    }
  }
}

For production (PageSpace hosted app):

{
  "mcpServers": {
    "pagespace": {
      "command": "<REPLACE_WITH_NODE_PATH>",
      "args": [
        "<REPLACE_WITH_NPM_GLOBAL_PATH>/pagespace-mcp/index.js"
      ],
      "env": {
        "PAGESPACE_API_URL": "https://your-pagespace-domain.com",
        "PAGESPACE_AUTH_TOKEN": "<YOUR_PAGESPACE_MCP_TOKEN_HERE>"
      }
    }
  }
}

Alternative using npx (experimental - global install is recommended):

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

Note: The npx method may not work reliably with all MCP configurations. The global installation method shown above is the tested and recommended approach.

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 Page Operations

"Create an AI chat page called 'Brainstorming' in drive [drive-id]" "Move page [page-id] to position 3 under parent [parent-id]"

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