My Scroll MCP Server

This is the Model Context Protocol (MCP) server for My Scroll, enabling Claude to directly read and edit your scroll documents with line-level precision.

🔒 Secure by Design: Version 0.2.0+ uses API-based token validation, requiring no sensitive database keys on the client side.

Installation

npm install -g my-scroll-mcp

Features

• Line-based editing: Replace, insert, or delete specific lines
• HTML-aware: Automatic Prettier formatting
• Secure: API-based token validation with user-specific authentication
• Real-time sync: Changes appear immediately in the web editor
• No sensitive keys required: Fully secure without exposing database credentials

Available Tools

read_scroll

Read your current scroll document with line numbers.

replace_lines

Replace specific line(s) with new content.

• startLine (number): Starting line number (1-based)
• endLine (number, optional): Ending line number (defaults to startLine)
• content (string): New HTML content

insert_at_line

Insert new content at a specific line.

• lineNumber (number): Where to insert (1-based)
• content (string): HTML content to insert

delete_lines

Delete specific line(s).

• startLine (number): Starting line number (1-based)
• endLine (number, optional): Ending line number (defaults to startLine)

append_to_scroll

Add content to the end of your scroll.

• content (string): HTML content to append

prepend_to_scroll

Add content to the beginning of your scroll.

• content (string): HTML content to prepend

Setup Instructions

1. Generate an MCP Token

1. Go to your My Scroll app
2. Visit your profile/settings page
3. Create a new MCP token
4. Save the token securely (it's only shown once)

2. Configure Claude Desktop

Add this to your Claude Desktop MCP configuration file:

For production use:

{
  "mcpServers": {
    "my-scroll": {
      "command": "npx",
      "args": ["-y", "my-scroll-mcp@latest"],
      "env": {
        "MY_SCROLL_API_URL": "https://myscroll.ai",
        "MY_SCROLL_AUTH_TOKEN": "mcp_your_token_here"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "my-scroll": {
      "command": "npx",
      "args": ["-y", "my-scroll-mcp@latest"],
      "env": {
        "MY_SCROLL_API_URL": "http://localhost:3000",
        "MY_SCROLL_AUTH_TOKEN": "mcp_your_token_here"
      }
    }
  }
}

3. Test the Connection

Restart Claude Desktop and try:

"Read my scroll document"

Claude should be able to access your document and show it with line numbers!

Usage Examples

Basic Reading

"Show me the contents of my scroll"

Line Replacement

"Replace line 15 with a new heading: <h2>New Section</h2>"

Content Addition

"Add a new paragraph at the end about project conclusions"

Precise Editing

"Delete lines 8-10 and replace them with a code block showing the API example"

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 MY_SCROLL_AUTH_TOKEN is set in your MCP configuration

Connection Issues

• Ensure your My Scroll 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 endpoints:

• POST /api/documents/lines - All line operations
• POST /api/auth/mcp-token - Token management

See the API route files for detailed request/response schemas.