sparkle

Sparkle MCP Server exposes a secure, Claude-friendly API for interacting with your local file system and clipboard history within the Sparkle workspace. It focuses on safe file access restricted to the ~/Sparkle directory, advanced search and indexing, and a robust clipboard history accessible via MCP tools. Available tools include file operations (list_directory, search_files, get_relevant_files, read_file, write_file, move_file, create_directory, get_file_info), clipboard utilities (search_clipboard, get_clipboard_by_date, get_recent_clipboard, clipboard_stats), and system health checks (health_check). To use Sparkle, run the MCP server with the recommended Node-based setup and point Claude or any MCP client at the server entry points using the provided mcp-config snippet. Once running, you can perform operations like listing the Sparkle folder, searching for documents with patterns, reading texts or binary files, and querying your clipboard history with date filters or keyword searches. The server also supports indexing and pattern-based searching to help locate relevant files quickly, while maintaining strict sandboxing to prevent unauthorized access.

Prerequisites:

• Node.js (LTS) and npm installed on your system
• Access to a shell/terminal with internet

Option A: Quick npm install (Recommended)

1. Install the MCP server globally via npm:

npm install -g @every-env/sparkle-mcp-server

2. Use the provided MCP config in Claude or your client (see mcp_config in this document) and start the server if needed:

# Example: if your environment requires explicit start, otherwise Claude can launch via npx as configured

Option B: Run via npx (as configured in mcp_config)

1. Sparkle MCP Server can be run on-demand with npx as configured in the mcp_config:

npx -y @every-env/sparkle-mcp-server

Option C: From source (optional)

1. Clone the repository and install dependencies:

git clone https://github.com/EveryInc/sparkle-mcp-server.git
cd sparkle-mcp-server
npm install
npm run build

2. Link or run locally as needed per your environment.

Configuration:

• The server uses ~/Sparkle/.mcp-config.json for configuration. Sample configuration is described in the repository README and includes settings like sparkleFolder, maxFileSize, allowedExtensions, autoIndex, and watcherEnabled.

Notes and tips:

• Security: Access is sandboxed to the ~/Sparkle folder. Ensure this folder exists and is writable for proper operation.
• File size: The server supports binary files up to 100MB. Large files may require additional handling.
• Indexing: Automatic file indexing with 50KB content sampling aids search relevance. If performance issues arise, consider adjusting index settings or enabling/disabling autoIndex.
• Clipboard: Clipboard history is stored under ~/Sparkle/Pasteboard/. Ensure the Pasteboard folder exists and your clipboard app writes in supported formats (JSON or plain text).
• Configuration: The MCP config file for Claude/clients is typically located at ~/Sparkle/.mcp-config.json. Validate JSON syntax after edits.
• If you encounter startup issues, verify that the sparkle-mcp-server binary is available in PATH (or use npx as configured) and check logs for hints.
• Networking/permissions: Confirm that your environment permits the MCP server to listen on the required interface and that file permissions allow read/write access to the Sparkle directory.