A powerful Model Context Protocol (MCP) server that provides secure file access and clipboard history management for Claude AI and other MCP-compatible clients.
- Secure File Access: Restricted to
~/Sparklefolder for safe AI file operations - Advanced File Search: Pattern matching, content search, and relevance scoring
- Clipboard History: Search and query clipboard history from
~/Sparkle/Pasteboard/ - Binary File Support: Handles PDFs, images, and other binary files (up to 100MB)
- Smart File Indexing: Automatic file indexing with 50KB content sampling for search
- Multiple File Operations: Read, write, move, create directories, and get file info
npm install -g @every-env/sparkle-mcp-servergit clone https://github.com/EveryInc/sparkle-mcp-server.git
cd sparkle-mcp-server
npm install
npm run build
npm linkJust add this to your Claude Desktop config (~/.config/claude/config.json):
{
"mcpServers": {
"sparkle": {
"command": "npx",
"args": ["-y", "@every-env/sparkle-mcp-server"]
}
}
}That's it! Restart Claude Desktop and you're done. No installation needed!
If you prefer a local installation:
npm install -g @every-env/sparkle-mcp-serverThen use this config:
{
"mcpServers": {
"sparkle": {
"command": "sparkle-mcp"
}
}
}list_directory- List files and directoriessearch_files- Search with glob patterns (*,*.txt, etc.)get_relevant_files- AI-powered file search and rankingread_file- Read file contents (text and binary)write_file- Create or overwrite filesmove_file- Move or rename filescreate_directory- Create directoriesget_file_info- Get file metadata
search_clipboard- Search clipboard history with filtersget_clipboard_by_date- Get clipboard entries for a specific dateget_recent_clipboard- Get recent clipboard entriesclipboard_stats- Usage statistics and analytics
health_check- Server status and diagnostics
// List all files in Sparkle folder
list_directory({ path: "" })
// Search for all text files
search_files({ path: "", pattern: "*.txt" })
// Find relevant files with AI
get_relevant_files({ query: "my tax documents", maxFiles: 5 })// Search clipboard for specific text
search_clipboard({ query: "password", limit: 20 })
// Get today's clipboard
get_clipboard_by_date({ date: "2025-08-05" })
// Recent clipboard history
get_recent_clipboard({ days: 7, limit: 50 })~/Sparkle/ # Main Sparkle directory
├── README.txt # Welcome file (auto-created)
├── Pasteboard/ # Clipboard history
│ ├── 2025-08-05/ # Daily clipboard folders
│ │ ├── clipboard.json # Clipboard entries
│ │ └── ...
├── Documents/ # Your documents
├── Images/ # Your images
└── ... # Any other files/folders
The server supports multiple clipboard storage formats:
[
{
"timestamp": "2025-08-05T10:30:00Z",
"content": "Hello world",
"type": "text",
"metadata": {
"app": "Safari",
"size": 11
}
}
]2025-08-05 10:30:00 | text | Hello world
2025-08-05 10:31:15 | url | https://example.com
If you have a Swift Sparkle app, here's how to integrate:
import Foundation
class SparkleManager {
private let serverProcess: Process
init() {
serverProcess = Process()
serverProcess.executableURL = URL(fileURLWithPath: "/usr/local/bin/sparkle-mcp")
// Configure stdio pipes for MCP communication
}
func sendMCPRequest(_ request: MCPRequest) async throws -> MCPResponse {
// Implement MCP protocol communication
}
}// Search files
let searchResult = try await sparkleManager.sendMCPRequest(
MCPRequest(method: "tools/call", params: [
"name": "search_files",
"arguments": ["path": "", "pattern": "*.pdf"]
])
)
// Read file
let fileContent = try await sparkleManager.sendMCPRequest(
MCPRequest(method: "tools/call", params: [
"name": "read_file",
"arguments": ["path": "document.txt"]
])
)// Save clipboard to Pasteboard folder
func saveClipboard() {
let pasteboard = NSPasteboard.general
if let string = pasteboard.string(forType: .string) {
let clipboardEntry = ClipboardEntry(
timestamp: Date(),
content: string,
type: "text"
)
saveToSparkleFolder(clipboardEntry)
}
}
// Query clipboard history via MCP
let recentClipboard = try await sparkleManager.sendMCPRequest(
MCPRequest(method: "tools/call", params: [
"name": "get_recent_clipboard",
"arguments": ["days": 7, "limit": 50]
])
)The server uses ~/Sparkle/.mcp-config.json for configuration:
{
"version": "1.0.0",
"created": "2025-08-05T10:00:00Z",
"settings": {
"sparkleFolder": "~/Sparkle",
"maxFileSize": 104857600,
"allowedExtensions": ["*"],
"autoIndex": true,
"watcherEnabled": true
}
}- Sandboxed Access: Only
~/Sparklefolder is accessible - File Size Limits: 100MB maximum file size
- Path Validation: Prevents directory traversal attacks
- Rate Limiting: 100 requests per minute
- Safe File Types: Blocks executable files by default
# Clone and setup
git clone https://github.com/EveryInc/sparkle-mcp-server.git
cd sparkle-mcp-server
npm install
# Development mode
npm run dev
# Build
npm run build
# Test
npm test- Update version:
npm version patch|minor|major - Build:
npm run build - Publish:
npm publish --access public
# Check if installed correctly
which sparkle-mcp
# Test server manually
sparkle-mcp --help
# Check logs
tail -f ~/.config/claude/logs/sparkle.log- Ensure
~/Sparklefolder exists and is writable - Check file permissions:
chmod 755 ~/Sparkle - Verify Claude Desktop has proper permissions
- Create
~/Sparkle/Pasteboard/directory - Ensure your clipboard app saves to the correct format
- Check folder permissions
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
MIT License - see LICENSE file for details.
- Issues: https://github.com/EveryInc/sparkle-mcp-server/issues
- Documentation: https://github.com/EveryInc/sparkle-mcp-server/wiki
- Discussions: https://github.com/EveryInc/sparkle-mcp-server/discussions
Built with ❤️ by Every Inc