Search the web and return ranked results (title, URL, snippet).

Use this whenever you need current information, facts you are unsure about, or to find pages to read with fetch_url. No API key required.

Args:

• query (string): What to search for. Plain keywords work best.

• limit (number): Max results, 1-20 (default 5).

• response_format ('markdown' | 'json'): Output style (default 'markdown').

Returns a list of { title, url, snippet }. Follow up with fetch_url on a result's url to read it.

Example: { "query": "rust async runtime comparison", "limit": 5 }

Download a web page and return its readable content as clean text or Markdown (scripts, styles, nav and ads stripped).

Use after web_search to actually read a page, or whenever you have a URL whose content you need.

Args:

• url (string): The http(s) URL to fetch.

• format ('text' | 'markdown'): 'text' (default) for plain readable text, 'markdown' to preserve headings/links/lists.

Returns the page content. Long pages are truncated; fetch a more specific URL if needed.

Example: { "url": "https://example.com/article", "format": "markdown" }

Fetch a page and list all outbound hyperlinks (absolute URLs with their anchor text).

Useful for crawling, finding a specific subpage, or mapping a site section.

Args:

• url (string): The page to scan.

• limit (number): Max links to return, 1-200 (default 50).

Returns a list of { text, href }.

Example: { "url": "https://news.ycombinator.com", "limit": 30 }

Fetch a page and return its metadata: title, description, canonical URL and OpenGraph tags. Cheaper than fetching full content when you only need to identify a page.

Args:

• url (string): The page URL.

Returns { title, description, canonical, og }.

Example: { "url": "https://example.com" }

Make a raw HTTP request to any API and return status, headers and body. Use for REST/JSON APIs that need GET/POST/PUT/DELETE with custom headers or a body.

Args:

• url (string): Target URL.

• method ('GET'|'POST'|'PUT'|'PATCH'|'DELETE'): default 'GET'.

• headers (object): Optional header map, e.g. { "Authorization": "Bearer ..." }.

• body (string): Optional request body (send JSON as a stringified object).

Returns { status, statusText, headers, body }.

Example: { "url": "https://api.github.com/repos/nodejs/node", "headers": { "Accept": "application/vnd.github+json" } }

Evaluate a mathematical expression precisely. Use this for ANY arithmetic instead of computing in your head.

Supports +, -, *, /, ^, parentheses, functions (sqrt, sin, cos, log, etc.), constants (pi, e), and units (e.g. "5 km in miles", "2 GB in bytes").

Args:

• expression (string): The expression to evaluate.

Returns the result as a string.

Examples:

• { "expression": "(1234 * 5678) / 90" }

• { "expression": "sqrt(2) * 100" }

• { "expression": "120 km/h in m/s" }

Return the current date and time. Use this whenever you need to know "now", compute ages/durations, or timestamp something — never guess the date.

Args:

• timezone (string): Optional IANA timezone, e.g. "Europe/Madrid", "America/New_York", "UTC". Defaults to the system timezone.

Returns the ISO timestamp, a human-readable string, and component parts.

Example: { "timezone": "Asia/Tokyo" }

Read a file from the local filesystem. Text files are returned as-is (UTF-8); PDF files are detected automatically and their text is extracted page by page.

Args:

• path (string): Absolute or ~-relative file path.

• offset (number): Start reading at this 1-based line (default 1). Use with max_lines to page through big files.

• max_lines (number): Optional cap on lines returned.

• line_numbers (boolean): Prefix each line with "N: " (default false). Use before edit_lines, so you know the exact line numbers.

Returns the file contents. Use list_directory first if unsure of the path.

Example: { "path": "/project/README.md" } or { "path": "/app.py", "offset": 100, "max_lines": 50, "line_numbers": true }

Write text to a file, creating parent directories as needed. Overwrites by default; set append=true to append.

Args:

• path (string): Destination file path.

• content (string): Text to write.

• append (boolean): Append instead of overwrite (default false).

Returns a confirmation with bytes written.

Example: { "path": "~/notes.txt", "content": "hello", "append": true }

List entries in a directory with type (file/dir) and size.

Args:

• path (string): Directory path (default current working directory).

Returns a list of { name, type, size_bytes }.

Example: { "path": "~/project/src" }

Run a shell command and return its stdout, stderr and exit code. Runs through the system shell, so pipes, redirects and globs work. Killed after the configured timeout.

WARNING: This executes arbitrary commands on the local machine. Only use commands the user would approve.

Args:

• command (string): The shell command line to run.

• cwd (string): Optional working directory.

Returns exit code plus captured stdout/stderr.

Example: { "command": "ls -la | head", "cwd": "~/project" }

Run a snippet of code and return its output. Use this to compute, transform data, or test logic instead of doing it in your head.

Args:

• language ('python'|'node'|'bash'): Interpreter to use.

• code (string): The source code. Print results to stdout.

• stdin (string): Optional text piped to the program's stdin.

Returns exit code plus captured stdout/stderr. Killed after the configured timeout.

Example: { "language": "python", "code": "print(sum(range(100)))" }

Show a desktop notification to the user (via notify-send). Use to announce that a long task finished or that you need attention.

Args:

• title (string): Notification title.

• message (string): Notification body.

• urgency ('low'|'normal'|'critical'): Urgency level (default 'normal').

Example: { "title": "Done", "message": "Finished indexing 240 files." }

Report the mcptools server version and configuration. Call this when asked what version of mcptools is running, or which tool groups are enabled.

Args: none.

Returns { name, version, node, enabled_groups, disabled_groups, tool_overrides, config_path, data_dir }.

Search file contents under a directory with a regular expression (like grep -rn, but no shell quoting to get wrong). Skips binary files, .git and node_modules. Use this to find where something is defined or mentioned.

Args:

• path (string): Directory (or single file) to search.

• pattern (string): Regular expression, e.g. "function \w+Tools". Plain text works too.

• glob (string): Optional filename filter, e.g. ".ts" or "src/**/.js".

• context_lines (number): Lines of context around each match (default 0).

• max_results (number): Max matching lines returned (default 50).

Returns matches as file:line: text, grouped by file.

Example: { "path": "~/project", "pattern": "registerTool", "glob": "*.ts" }

Find files by name across a directory tree using a glob pattern. Use this instead of walking directories one list_directory call at a time. Skips .git and node_modules.

Args:

• path (string): Root directory to search (default ".").

• pattern (string): Glob, e.g. ".pdf", "**/.test.ts", "config". Matched against the path relative to root.

• max_results (number): Max files returned (default 100).

Returns matching paths with sizes.

Example: { "path": "~/Documents", "pattern": "*.pdf" }

Replace an exact string in a text file. Much safer than rewriting the whole file with write_file — the rest of the file is untouched. The old_string must match exactly (including whitespace) and, unless replace_all is true, must appear exactly once; include surrounding lines to make it unique. If you cannot reproduce the text exactly, use edit_lines instead.

Args:

• path (string): File to edit.

• old_string (string): Exact text to find.

• new_string (string): Replacement text.

• replace_all (boolean): Replace every occurrence (default false).

• dry_run (boolean): Preview the change without writing (default false).

Returns a confirmation plus the edited region with line numbers, so you can verify without re-reading the file.

Example: { "path": "~/app/config.py", "old_string": "DEBUG = True", "new_string": "DEBUG = False" }

Edit a file by line numbers: replace a line range, insert text, or delete lines. Use read_file with line_numbers=true first to get the exact numbers. Prefer edit_file when you can copy the exact text; use this when you know the location but not the exact characters. IMPORTANT: line numbers shift after every edit — re-read the file before making another line-based edit.

Args:

• path (string): File to edit.

• mode ('replace'|'insert_before'|'insert_after'|'delete'): What to do (default 'replace').

• start_line (number): First line affected (1-based, inclusive).

• end_line (number): Last line affected (default start_line). Ignored for inserts.

• new_text (string): The new lines (required except for delete).

• dry_run (boolean): Preview the change without writing (default false).

Returns a confirmation plus the edited region with line numbers.

Example: { "path": "~/app.py", "mode": "replace", "start_line": 12, "end_line": 14, "new_text": "def main():\n run()" }

Convert a local PDF into structured JSON: document metadata (title, author...), page count, and the text of each page. Use read_file for a quick plain-text read; use this when you need page structure, metadata, or a JSON file other tools can consume (e.g. json_query).

Args:

• path (string): The PDF file.

• output_path (string): Optional .json destination. If set, the full JSON is written there and only a summary is returned — best for large PDFs.

Returns { source, total_pages, metadata, pages: [{ page, text }] }.

Example: { "path": "/papers/attention.pdf", "output_path": "/papers/attention.json" }

Download a URL to a local file, binary-safe (PDFs, images, archives...). Use fetch_url for reading web pages as text; use this when you need the actual file on disk — e.g. download a PDF, then read_file it to extract the text.

Args:

• url (string): The file URL (http/https).

• path (string): Destination file path. Parent directories are created.

Returns the saved path, size and content type.

Example: { "url": "https://arxiv.org/pdf/1706.03762", "path": "~/papers/attention.pdf" }

Run a SQL statement against a local SQLite database file and return the rows or change count. Use this to query or modify structured data instead of inventing values.

To explore an unfamiliar database, first run: SELECT name FROM sqlite_master WHERE type='table'.

Args:

• db_path (string): Path to the .sqlite/.db file (created if missing unless read_only).

• sql (string): A single SQL statement. SELECT/PRAGMA return rows; INSERT/UPDATE/DELETE return a change count.

• params (array): Optional positional parameters for ? placeholders.

• read_only (boolean): Open read-only (default false).

Returns rows (for SELECT) or { changes, lastInsertRowid }.

Example: { "db_path": "~/data/app.db", "sql": "SELECT * FROM users WHERE age > ?", "params": [18] }

Extract a slice of a local JSON or CSV file with a path query, instead of reading the whole file into context. CSV files are parsed using the first row as headers (every row becomes an object).

Path syntax: "." is the whole document, ".key.subkey" descends into objects, "[0]" indexes an array, "[]" maps over every element. Examples: ".users[0].name", ".items[].price", ".results[]" .

Args:

• path (string): The .json or .csv file.

• query (string): Path query (default "." — but prefer something narrower).

• limit (number): If the result is an array, max elements returned (default 100).

Returns the matching slice as JSON.

Example: { "path": "~/data/users.json", "query": ".users[].email" }

Look up a topic on Wikipedia and return a concise summary (with the page URL). Prefer this over web_search for encyclopedic facts about people, places, concepts and events.

Args:

• query (string): The topic or article title to look up.

• lang (string): Wikipedia language code (default 'en').

Returns { title, summary, url }.

Example: { "query": "Alan Turing" }

Get the current weather and a short forecast for a place (via open-meteo, no API key). Use this for any "what's the weather" question — never guess.

Args:

• location (string): City or place name, e.g. "Madrid", "Tokyo, Japan".

• days (number): Forecast days, 1-7 (default 3).

Returns current conditions plus a daily min/max forecast.

Example: { "location": "Barcelona", "days": 3 }

Fetch and parse an RSS or Atom feed, returning the latest items. Use for news sites, blogs, podcasts and release feeds — cheaper and more current than web_search when you know the feed.

Args:

• url (string): The feed URL (e.g. "https://news.ycombinator.com/rss").

• limit (number): Max items returned (default 10).

Returns items as { title, link, date, summary }.

Example: { "url": "https://lwn.net/headlines/rss", "limit": 5 }

Search Hacker News stories (Algolia API, no key). Great for tech news, library/tool opinions and discussions.

Args:

• query (string): Search terms. Empty string returns the current front page.

• sort ('relevance'|'date'): Ranking (default 'relevance').

• limit (number): Max stories (default 10).

Returns stories with points, comment count and discussion link.

Example: { "query": "llama.cpp", "sort": "date" }

Search arXiv for scientific papers (no API key). To read a paper: take pdf_url from a result, download_file it, then read_file the PDF.

Args:

• query (string): Search terms, e.g. "mixture of experts quantization".

• sort ('relevance'|'latest'): Ranking (default 'relevance').

• limit (number): Max papers (default 5).

Returns papers with title, authors, date, abstract and pdf_url.

Example: { "query": "speculative decoding", "sort": "latest" }

Fetch the transcript (captions) of a YouTube video as plain text. Use to summarize or answer questions about a video without watching it. Fails cleanly if the video has no captions.

Args:

• video (string): Video URL or 11-character video ID.

• lang (string): Preferred caption language code (default 'en'; falls back to whatever exists).

Returns the transcript text.

Example: { "video": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }

Persist a fact/note under a key so you can recall it in future turns or sessions. Overwrites an existing key.

Args:

• key (string): Short unique identifier, e.g. "user_timezone".

• value (string): The information to remember.

• tags (string): Optional comma-separated tags for later filtering.

Example: { "key": "user_name", "value": "Sergio", "tags": "profile" }

Retrieve saved notes. Give an exact key for a single note, or a search term to match across keys/values/tags. Call this when you might already know something the user told you earlier.

Args:

• key (string): Optional exact key to fetch.

• search (string): Optional text to match (substring, case-insensitive).

• limit (number): Max results for a search (default 10).

Returns matching { key, value, tags, updated_at } records.

Example: { "search": "timezone" }

List all saved memory keys (with tags and timestamps) without their full values. Use to see what you have stored.

Args: none.

Returns a list of { key, tags, updated_at }.

Delete a saved memory by key.

Args:

• key (string): The key to delete.

Example: { "key": "user_name" }

Add a task to the persistent todo list. When given a multi-step job, add each step first, then work through them with todo_done — this keeps you from forgetting steps.

Args:

• text (string): The task description.

Returns the new task id.

Example: { "text": "Write tests for the parser" }

List tasks on the todo list (pending by default). Check this at the start of a work session to see what is still open.

Args:

• include_done (boolean): Also show completed tasks (default false).

Returns tasks as a checklist with ids.

Mark a todo as done by id (from todo_list). Set remove=true to delete it entirely instead.

Args:

• id (number): The task id.

• remove (boolean): Delete the task instead of marking done (default false).

Example: { "id": 3 }

Embed and index a local file or directory into the semantic search store so you can retrieve relevant passages later with rag_search. Re-indexing the same source replaces its old chunks.

Requires an embedding server (LM Studio or llama.cpp) running with an embedding model loaded.

Args:

• path (string): File or directory to index. Directories are walked for text/code files.

• max_files (number): Cap on files when indexing a directory, 1-2000 (default 200).

Returns the number of files and chunks indexed.

Example: { "path": "~/project/docs" }

Search previously indexed documents by meaning and return the most relevant passages with their source files. Use this to ground answers in the user's own files/docs that you indexed with rag_index.

Requires an embedding server (LM Studio or llama.cpp) running with an embedding model loaded.

Args:

• query (string): What to look for (a question or topic).

• top_k (number): Number of passages to return, 1-20 (default 5).

Returns ranked { source, score, text } passages.

Example: { "query": "how is authentication handled", "top_k": 5 }

List the source files currently indexed in the RAG store, with the chunk count for each. Use this to see what is indexed and to get the exact source paths needed by rag_delete.

Returns a list of { source, chunks } and overall store totals.

Example: {}

Remove all indexed chunks for a source from the RAG store. The source must match the path stored at index time (an absolute path) — use rag_list to find exact paths. The original file on disk is not touched.

Args:

• source (string): Source path to delete, exactly as shown by rag_list.

Returns the number of chunks deleted and the updated store totals.

Example: { "source": "/tmp/ragcorpus/cooking.md" }