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
- Clone or download this project:
cd ~/Documents/GitHub/scratchpad
- Install dependencies:
pip install -r requirements.txt
- Make the server executable:
chmod +x src/server.py
Usage
As an MCP Server
Add to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"scratchpad": {
"command": "python3",
"args": ["/path/to/scratchpad/src/server.py"]
}
}
}
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, notepriority(optional): One of: high, medium, low
Example:
{
"note": "Add error handling to API client",
"type": "bug",
"priority": "high"
}
5. scratchpad_update_focus
Update your current focus/task.
Parameters:
task(required): Description of current task (max 200 chars)
Example:
{
"task": "Implementing user authentication flow"
}
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:
{
"note": "Research better caching strategy for API calls"
}
7. scratchpad_mark_completed
Mark an item as completed. Adds it to "Completed Today" with timestamp and removes it from Interruptions/Review Later.
Parameters:
note(required): The completed item (max 500 chars)
Example:
{
"note": "Fixed authentication bug in login flow"
}
8. scratchpad_archive_item
Archive/dismiss an item. Moves it to "Archived / Dismissed" section and removes it from Interruptions/Review Later.
Parameters:
note(required): The item to archive (max 500 chars)
Example:
{
"note": "Old idea that's no longer relevant"
}
🔒 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:
chmod 755 ~/Desktop/scratchpad
chmod 644 ~/Desktop/scratchpad/scratchpad.md
2. Regular Cleanup
Monitor scratchpad file sizes and archive old content regularly.
3. Error Monitoring
Check stderr output for security warnings:
python3 src/server.py 2>scratchpad-errors.log
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:
cd ~/Documents/GitHub/scratchpad
python3 src/server.py
Debugging
The server outputs operational info to stderr:
🔒 Scratchpad MCP initialized
📁 Scratchpad location: /Users/username/Desktop/scratchpad/scratchpad.md
✅ Created scratchpad: /Users/username/Desktop/scratchpad/scratchpad.md
📝 Logged: Bug - Add error handling...
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.