AI Scratchpad MCP Server

A secure Model Context Protocol (MCP) server for managing a global AI scratchpad file. Track interruptions, ideas, tasks, and maintain focus across all your projects with a single scratchpad on your Desktop.

🔒 Security Features

• Input Validation: Comprehensive sanitization of all user inputs

• Rate Limiting: 60 requests/minute protection against abuse

• Path Traversal Protection: Workspace boundary enforcement

• Content Size Limits: Max 1MB file size, 500 char notes

• Allowed Directory Restrictions: Only approved locations

• Error Sanitization: Prevents sensitive information disclosure

Features

• 📝 Log Interruptions: Capture ideas without losing focus

• 🎯 Track Current Focus: Update and maintain your current task

• 🔄 Review Later: Queue items for follow-up consideration

• ✅ Mark Completed: Track accomplishments with timestamps

• 🗑️ Archive Items: Dismiss or archive old ideas

• 📊 Auto Statistics: Automatically tracks logged, completed, and archived items

• 🌍 Global Scratchpad: Single scratchpad on Desktop accessible from all projects

• 📋 Organized Storage: Markdown-based scratchpad with sections

• 🔐 Secure by Design: Input validation, rate limiting, path protection

• ⚡ Fast & Lightweight: Minimal dependencies, quick operations

Installation

Prerequisites

• Python 3.8+

• MCP-compatible client (Claude Desktop, etc.)

Setup

1. Clone or download this project:

2. Install dependencies:

3. Make the server executable:

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

The scratchpad will be created at ~/Desktop/scratchpad/scratchpad.md and accessible from all your projects.

Available Tools

1. scratchpad_create

Create a new scratchpad file at ~/Desktop/scratchpad/scratchpad.md.

No parameters required.

2. scratchpad_get_path

Get the scratchpad file path and check if it exists.

No parameters required.

3. scratchpad_read

Read the entire scratchpad contents.

No parameters required.

4. scratchpad_log_interruption

Log an idea, bug, or interruption.

Parameters:

• note (required): The note to log (max 500 chars)

• type (optional): One of: idea, bug, feature, question, contact, refactor, task, note

• priority (optional): One of: high, medium, low

Example:

5. scratchpad_update_focus

Update your current focus/task.

Parameters:

• task (required): Description of current task (max 200 chars)

Example:

6. scratchpad_add_to_review_later

Add an item to the "To Review Later" section for follow-up.

Parameters:

• note (required): The item to add (max 500 chars)

Example:

7. scratchpad_mark_completed

Mark an item as completed. Adds it to "Completed Today" with timestamp.

Parameters:

• note (required): The completed item (max 500 chars)

Example:

8. scratchpad_archive_item

Archive/dismiss an item. Moves it to "Archived / Dismissed" section.

Parameters:

• note (required): The item to archive (max 500 chars)

Example:

🔒 Security Configuration

Scratchpad Location

The scratchpad is always located at:

• Primary: ~/Desktop/scratchpad/scratchpad.md

• Fallback: ~/scratchpad/scratchpad.md (if Desktop doesn't exist)

This fixed location prevents path traversal attacks and unauthorized file access.

File Restrictions

• Extensions: Only .md, .txt, .markdown

• Max size: 1MB

• Path length: 256 characters max

Rate Limiting

• Limit: 60 requests per minute

• Window: Rolling 60-second window

• Scope: Per-process (resets on server restart)

Input Sanitization

All inputs are sanitized to prevent:

• Path traversal attacks (.., ~)

• Command injection (`, $)

• XSS attempts (<script>, javascript:)

• Null byte injection (\x00)

Content Limits

• Notes: 500 characters maximum

• Tasks: 200 characters maximum

• File size: 1MB maximum

Security Best Practices

1. File Permissions

Ensure the scratchpad directory has appropriate permissions:

2. Regular Cleanup

Monitor scratchpad file sizes and archive old content regularly.

3. Error Monitoring

Check stderr output for security warnings:

Troubleshooting

"Rate limit exceeded" Error

Wait for the specified time or restart the server to reset the rate limiter.

"Scratchpad not found" Error

The scratchpad doesn't exist yet. Use scratchpad_create to create it at ~/Desktop/scratchpad/scratchpad.md.

Desktop Not Found

If ~/Desktop doesn't exist, the scratchpad will be created at ~/scratchpad/scratchpad.md instead.

Development

Testing

Test the server directly:

Debugging

The server outputs operational info to stderr:

License

MIT License - feel free to use and modify as needed.

Security Reporting

If you discover a security vulnerability, please report it privately rather than creating a public issue.