Baloosearch MCP Server
A Model Context Protocol (MCP) server that provides file search functionality using KDE's baloosearch tool.
Description
This MCP server exposes a tool that allows AI assistants to search for terms in files using the KDE baloosearch utility. It enables semantic search across your file system to find relevant documents and content.
The server implements the Model Context Protocol specification and can be used with any MCP-compatible client, such as Claude Desktop or other AI assistants that support the protocol.
Features
- Search for terms in files using KDE baloosearch
- Configurable search parameters (limit, offset, directory, file type)
- Advanced query syntax support (AND, OR, NOT, phrases, wildcards)
- Property-based searches (Artist, Author, etc.)
- File type filtering (Audio, Document, Image, etc.)
- JSON output of search results
- Full MCP compliance for integration with AI assistants
Prerequisites
- Node.js (v18 or higher)
- KDE baloosearch tool (typically installed with KDE desktop environment)
Installation
npm install
Running with npx
You can run this MCP server directly using npx without installing it globally:
npx baloosearch-mcp
This will start the MCP server that can be used with any MCP-compatible AI assistant.
Usage
Starting the Server
npm start
The server will start and listen for MCP requests via stdio.
Testing the Baloosearch Tool
npm run test-tool
This runs a direct test of the baloosearch functionality.
Tools
search_files
Search for terms in files using KDE baloosearch.
Query Syntax Examples:
- Simple search:
"project plan" - Multiple terms:
"budget AND marketing"(finds files with both terms) - OR search:
"report OR presentation"(finds files with either term) - Phrase search:
"\"strategic plan\""(finds exact phrase) - Exclusion:
"financial -tax"(finds files with "financial" but not "tax") - Wildcard:
"report*"(finds files with words starting with "report") - Property search:
"Artist:\"Coldplay\""(finds audio files by artist) - File type search:
"type:Audio"(finds audio files) - Combined expressions:
"(type:Audio AND Artist:\"Coldplay\") OR (type:Document AND subject:\"music\")" - Property comparisons:
"rating>3","modified>2024-01-01"
Supported File Types:
"Archive"(zip, tar, etc.)"Folder"(directories)"Audio"(mp3, wav, etc.)"Video"(mp4, avi, etc.)"Image"(jpg, png, etc.)"Document"(pdf, doc, etc.)"Spreadsheet"(xls, xlsx, etc.)"Presentation"(ppt, pptx, etc.)
"Text"(txt, etc.)
Common Properties for All Files:
filename(name of the file)modified(last modification date)mimetype(MIME type of file)tags(user-defined tags)rating(numeric rating 0-10)userComment(user comments)
Audio-Specific Properties:
Artist,Album,AlbumArtist,Composer,LyricistGenre,Duration,BitRate,Channels,SampleRateTrackNumber,ReleaseYear,Comment
Document-Specific Properties:
Author,Title,Subject,KeywordsPageCount,WordCount,LineCountLanguage,Copyright,PublisherCreationDate,Generator
Media-Specific Properties (Video/Images):
Width,Height,AspectRatio,FrameRate
Image-Specific Properties:
ImageMake,ImageModel,ImageDateTimePhotoFlash,PhotoFNumber,PhotoISOSpeedRatingsPhotoGpsLatitude,PhotoGpsLongitude,PhotoGpsAltitude
Parameters:
query(string, required): The search query terms. Supports advanced search syntax:AND: Requires both terms (e.g.,"budget AND marketing")OR: Requires either term (e.g.,"report OR presentation")NOTor-: Excludes terms (e.g.,"financial -tax"or"financial NOT tax")- Phrase search: Use quotes for exact phrases (e.g.,
"\"project plan\"") - Wildcards: Use
*for partial matching (e.g.,"report*") - Property searches:
"Artist:\"Coldplay\""or"Author:\"Smith\"" - File type filters:
"type:Audio","type:Document","type:Image", etc. - Property comparisons:
"rating>3","modified>2024-01-01" - Grouping: Use parentheses to group terms (e.g.,
"(budget OR finance) AND 2024")
limit(number, optional): Maximum number of results to return (default: 10)offset(number, optional): Offset from which to start the search (default: 0)directory(string, optional): Limit search to specified directory (absolute path)type(string, optional): Type of data to be searched. Common types include:"Archive"(zip, tar, etc.)"Folder"(directories)"Audio"(mp3, wav, etc.)"Video"(mp4, avi, etc.)"Image"(jpg, png, etc.)"Document"(pdf, doc, etc.)"Spreadsheet"(xls, xlsx, etc.)"Presentation"(ppt, pptx, etc.)
"Text"(txt, etc.) Note: This parameter is an alternative to using "type:" in the query.
Returns:
- JSON array of objects containing file paths that match the search criteria
Testing with Command Line
You can test the server directly from the command line using echo and pipes:
List Available Tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/server/mcp-server.js
Search for Files
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"test","limit":3}}}' | node src/server/mcp-server.js
Advanced Search Examples
# Search for files with both "budget" and "marketing"
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"budget AND marketing","limit":5}}}' | node src/server/mcp-server.js
# Search for audio files by a specific artist
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Audio AND Artist:\"ArtistName\"","limit":5}}}' | node src/server/mcp-server.js
# Search for documents with high ratings
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Document AND rating>3","limit":5}}}' | node src/server/mcp-server.js
# Search for recent documents
echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Document AND modified>2024-01-01","limit":5}}}' | node src/server/mcp-server.js
# Search for images with specific properties
echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Image AND PhotoFNumber<2.8","limit":5}}}' | node src/server/mcp-server.js
Integration with Claude Desktop
To use this server with Claude Desktop:
- Add the following to your
claude_desktop_config.json:
{
"mcpServers": {
"baloosearch": {
"command": "node",
"args": ["/path/to/baloosearch-mcp/src/server/mcp-server.js"],
"env": {}
}
}
}
- Restart Claude Desktop
- The baloosearch tool will be available in the tools list
Project Structure
baloosearch-mcp/
├── src/
│ ├── server/
│ │ └── mcp-server.js # Main MCP server implementation
│ ├── tools/
│ │ └── baloosearch-tool.js # Baloosearch tool implementation
│ ├── test-tool.js # Test script for the tool
│ └── test-server.js # Test script for the server
├── test/
│ ├── integration.js # Integration test script
│ └── server-test.sh # Server test script
├── package.json # Project configuration
└── README.md # This file
Development
Running Tests
# Test the baloosearch tool directly
npm run test-tool
# Test the MCP server startup
npm run test-server
Publishing to npm
To publish this package to npm:
- Create an account at npmjs.com if you don't have one
- Log in to npm:
npm login - Publish the package:
npm publish
After publishing, users will be able to run your MCP server using:
npx baloosearch-mcp
Modifying the Server
The main server implementation is in src/server/mcp-server.js. You can add additional tools or modify existing ones by following the same pattern as the search_files tool.
Modifying the Baloosearch Tool
The baloosearch tool implementation is in src/tools/baloosearch-tool.js. You can modify the search parameters or add additional functionality as needed.
Troubleshooting
"baloosearch: command not found"
Make sure you have KDE desktop environment installed with baloosearch available. You can test this by running:
which baloosearch
Server exits immediately
This is normal behavior for MCP servers using stdio transport. The server waits for JSON-RPC messages via stdin/stdout.
No search results
Make sure your baloosearch index is up to date. You can update it by running:
balooctl monitor
License
This project is licensed under the MIT License.