Skip to main content
Glama
el95149

Baloosearch MCP Server

by el95149
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

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.

Related MCP server: Local Explorer MCP

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, Lyricist

  • Genre, Duration, BitRate, Channels, SampleRate

  • TrackNumber, ReleaseYear, Comment

Document-Specific Properties:

  • Author, Title, Subject, Keywords

  • PageCount, WordCount, LineCount

  • Language, Copyright, Publisher

  • CreationDate, Generator

Media-Specific Properties (Video/Images):

  • Width, Height, AspectRatio, FrameRate

Image-Specific Properties:

  • ImageMake, ImageModel, ImageDateTime

  • PhotoFlash, PhotoFNumber, PhotoISOSpeedRatings

  • PhotoGpsLatitude, 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")

    • NOT or -: 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:

  1. Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "baloosearch": {
      "command": "node",
      "args": ["/path/to/baloosearch-mcp/src/server/mcp-server.js"],
      "env": {}
    }
  }
}

  1. Restart Claude Desktop

  2. 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:

  1. Create an account at npmjs.com if you don't have one

  2. Log in to npm:

    npm login

  3. 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.

Available Tools

2 tools
search_filesC

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")"

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe search query terms. Supports advanced search syntax: - Basic search: Simple terms like "project plan" - AND queries: "budget AND marketing" (requires both terms) - OR queries: "report OR presentation" (requires either term) - NOT queries: "financial -tax" or "financial NOT tax" (excludes terms) - Phrase searches: "\"exact phrase\"" (matches exact phrases) - Wildcards: "report*" (matches partial words) - Property searches: "Artist:\"Coldplay\"" or "Author:\"Smith\"" - File type filters: "type:Audio", "type:Document", "type:Image", etc. - Grouping: Use parentheses "(term1 AND term2) OR term3" - 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, Lyricist - Genre, Duration, BitRate, Channels, SampleRate - TrackNumber, ReleaseYear, Comment Document-specific properties: - Author, Title, Subject, Keywords - PageCount, WordCount, LineCount - Language, Copyright, Publisher - CreationDate, Generator Media-specific properties (Video/Images): - Width, Height, AspectRatio, FrameRate Image-specific properties: - ImageMake, ImageModel, ImageDateTime - PhotoFlash, PhotoFNumber, PhotoISOSpeedRatings - PhotoGpsLatitude, PhotoGpsLongitude, PhotoGpsAltitude
limitNoMaximum number of results to return (default: 10)
offsetNoOffset from which to start the search (default: 0)
directoryNoLimit search to specified directory (absolute path)
typeNoType 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.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it explains the query syntax extensively, it doesn't address key behavioral aspects: whether this is a read-only operation, what permissions are required, how results are returned (format, pagination), error conditions, or performance characteristics. The description focuses on syntax but misses operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, but then becomes a lengthy syntax reference. While the syntax examples are helpful, they might be better placed in parameter documentation. The description could be more concise by focusing on high-level guidance rather than duplicating detailed syntax that's already in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 5 parameters, 100% schema coverage, and no output schema, the description provides adequate context about what the tool does and how to structure queries. However, it lacks information about result format, error handling, and operational constraints. The completeness is minimally adequate but has clear gaps in behavioral transparency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds query syntax examples that complement the schema's query parameter documentation, but doesn't provide additional semantic context for the other parameters (limit, offset, directory, type). The baseline is 3 when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search for terms in files using KDE baloosearch.' It specifies the verb ('search'), resource ('files'), and technology ('KDE baloosearch'). However, it doesn't explicitly differentiate from the sibling tool 'show_file_words', which might have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It mentions the sibling tool 'show_file_words' in the context, but doesn't explain how they differ or when to choose one over the other. There's no mention of prerequisites, limitations, or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

show_file_wordsA

Show indexed content & meta-data in a file using KDE balooshow.

This tool retrieves all the indexed words & meta-data from a specific file that has been indexed by KDE's Baloo search system.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe absolute path to the file to show indexed words & meta-data for

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the tool's behavior as a retrieval operation ('retrieves all the indexed words & meta-data'), which implies it's read-only and non-destructive. However, it doesn't mention potential limitations like file size constraints, indexing status requirements, or error conditions. It adds some context about the Baloo system but lacks detailed behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that efficiently convey purpose and context. The first sentence introduces the tool and technology, while the second elaborates on what it retrieves. There's minimal redundancy, though the second sentence could be slightly more concise by integrating with the first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does and the technology involved, but doesn't cover output format, error handling, or dependencies on the Baloo indexing status. For a tool with no annotations or output schema, more completeness would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for its single parameter 'path', clearly documenting it as 'The absolute path to the file to show indexed words & meta-data for'. The description reinforces this by mentioning 'from a specific file' but doesn't add significant semantic value beyond what the schema already provides. With 0 parameters beyond the documented one, the baseline is appropriately high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('retrieves all the indexed words & meta-data'), the resource ('from a specific file'), and the technology context ('using KDE balooshow', 'indexed by KDE's Baloo search system'). It distinguishes this tool from its sibling 'search_files' by focusing on showing content from a single file rather than searching across files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by mentioning 'indexed by KDE's Baloo search system', suggesting the tool is for files already indexed. However, it doesn't explicitly state when to use this tool versus the sibling 'search_files' or provide any exclusion criteria. The guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: search_files searches across files for terms, while show_file_words displays indexed content and metadata for a specific file. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern with snake_case: search_files and show_file_words. The naming is predictable and readable throughout.

Tool Count2/5

With only 2 tools, the server feels thin for its apparent scope of file search and metadata display. A typical search system might include additional operations like listing indexed files, updating indexes, or filtering results, making this set under-scoped.

Completeness2/5

Inferring the domain as file search and indexing, there are significant gaps: no tools for managing the index (e.g., refresh, status), listing available files or properties, or performing advanced queries beyond basic search. This limits agent workflows and could lead to dead ends.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • File Search Server

    liu10250510
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables intelligent file searching in local directories using natural language queries. Supports searching by file type, filename patterns, and content across multiple formats including PDF, Word, Excel, and text files with AI-powered relevance scoring.

  • Local Explorer MCP

    bgauryy
    A
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI assistants to intelligently search and explore local file systems using native Unix commands (ripgrep, find, ls) with token-optimized output, automatic pagination, and multi-layer security validation.
    164
    2

  • fd-mcp

    thhart
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides fast file search capabilities using fd (a modern find alternative), enabling AI assistants to efficiently navigate codebases, search file contents with ripgrep, and execute commands on matched files.
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/el95149/baloosearch-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server