home / mcp / keyword mcp server
A minimal MCP server built with FastAPI that searches for a specified keyword within a file and returns the number of occurrences.
Configuration
View docs{
"mcpServers": {
"ansariusaid-mcp-keyword-search": {
"url": "http://127.0.0.1:8000"
}
}
}This MCP Server provides a fast, RESTful keyword search capability you can run locally or integrate into your tooling. It searches text files for a given keyword, returns matching lines with line numbers and occurrence counts, and lets you toggle case sensitivity. It is designed to be simple to deploy and easy to query from an MCP client or your own tooling.
You run the MCP server locally and query it via HTTP to search for keywords inside text files. Start a server in one terminal, then from another terminal or your integration code, send a search request. The server will return all matching lines with line numbers and how many times the keyword appears on each line. You can toggle between case-sensitive and case-insensitive searches to suit your data.
Typical usage patterns include searching a single file for a keyword across a scanned corpus, filtering results by line content, and verifying the total number of matches per file. Use a client that makes a POST request to the search endpoint with the target file path, the keyword, and a flag for case sensitivity. The response includes the file path, the keyword, total matches, and a list of matches with line numbers, content, and per-line occurrence counts.
Key endpoints you will interact with from a client are the search endpoint to retrieve results, a health endpoint to confirm the server is alive, and the root endpoint to display server information. Integrate these into your tooling to monitor status, perform searches, and surface basic server metadata.
Prerequisites you need before running the MCP server are Python 3.8+ and a working Python environment. A virtual environment is recommended to isolate dependencies.
Step by step commands to set up and run the server locally:
python3 -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt
python server.py # starts the MCP Keyword Search Server on http://127.0.0.1:8000
# In another terminal, you can run a test client if available
python test_client.pyConfiguration and runtime notes you should consider when using this server include how to reach it from your MCP client, how to format the file path you want to search, and how to specify case sensitivity. The server exposes a straightforward HTTP API for search, health, and status information. If you need to adapt it for production, you can run it behind a reverse proxy and secure access to the endpoints.
Security considerations: limit access to the running server to trusted environments, validate file paths to avoid arbitrary file access, and handle errors gracefully in your client to account for missing files or unreadable text. The server reports errors for missing files, non-text files, and invalid paths to help you diagnose issues quickly.
Examples of how you might integrate this MCP server into a workflow include automated document searches, indexing pipelines, and QA processes that need quick keyword-based scanning of large text collections.
The MCP server runs locally and is reachable over HTTP. The default address is http://127.0.0.1:8000, and you can perform searches using the search endpoint, check health with the health endpoint, and retrieve basic server information from the root endpoint.
If the server does not start, verify that Python is installed and that port 8000 is not used by another process. If you encounter 404 or 400 errors for a search request, confirm the file_path points to a readable text file and that the keyword is provided with the appropriate case sensitivity flag.
POST to /search with file_path, keyword, and case_sensitive to retrieve lines containing the keyword, with per-line occurrences and line numbers.
GET /health to verify server status is healthy.
GET / to fetch server information and basic metadata.