mcp-tools

A ready-to-use MCP toolkit that gives AI agents practical local capabilities: document OCR, speech recognition, speaker diarization, image understanding, document conversion, and browser-based web access. An optional Brave Search launcher adds API-backed search.

Built for developers running MCP clients on Linux or WSL2, mcp-tools provides seven stdio server entry points, 33 repository-owned tools, reproducible uv environments, and one repository-relative launcher. Start with a CPU-only MCP round trip; add the CUDA or external-service profiles you actually need.

OCR · ASR · diarization · vision · PDF/SVG conversion · browser fetch · web search

Quick start · Capabilities · Client setup · Examples · Contributing

Why this project exists

Giving an agent useful local media and document abilities often means operating several unrelated runtimes: one for OCR, another for speech, a browser process, a document renderer, and a vision backend. This repository keeps those services behind the same MCP stdio interface while preserving separate, locked runtime profiles where their dependencies conflict.

The local inference services communicate with loopback backends and do not send input documents, audio, or images to a hosted inference API. Model downloads, Browser Fetch targets, and Brave Search still use the network. Model weights and browser binaries are not stored in Git.

Related MCP server: paper-intelligence

Capabilities

The standalone asr-pipeline CLI exposes the same long-audio transcription, diarization, timestamping, and merge stages used by transcribe_diarized.

The optional PDF Local Links VS Code extension is a local fork of vscode-pdf. It opens PDF and other local file references in VS Code, including cross-repository files in the same WSL connection. It has its own Node build and VSIX package and is not an MCP server or a Python dependency.

Quick start

The shortest reliable path exercises a real server through MCP without CUDA, a browser, an API key, or committed binary fixtures. It requires Linux x86-64 or WSL2, Git, and uv.

git clone https://github.com/lanxiukai/mcp-tools.git
cd mcp-tools

# Restore the locked Python 3.12 CPU environment.
uv sync --project environments/mcp-local --locked

# Inspect installed runtimes and optional model-backed capabilities.
bin/mcp-tools doctor

# Create a temporary PDF, call pdf_to_text over MCP stdio, and verify the result.
environments/mcp-local/.venv/bin/python examples/pdf_to_text_demo.py

Successful output ends with:

Connected tools: inspect_pdf_links, resolve_pdf_destination, markdown_to_pdf, html_to_pdf, svg_to_png, pdf_to_text
Extracted text: Hello from mcp-tools over MCP stdio.
MCP round trip: OK

The demo removes its temporary files. See examples/ for its implementation.

Connect the first server

Every service is launched through bin/mcp-tools, so client configuration needs one executable path plus a stable service argument instead of a separate Python and script path for each component.

For Codex CLI, run this from the repository root:

codex mcp add mcp-tools-format -- "$(pwd)/bin/mcp-tools" format-conversion
codex mcp list

Then ask the client:

Extract the embedded text from /absolute/path/to/report.pdf with pdf_to_text.

For Claude Desktop, Cursor, VS Code, OpenCode, and generic clients, see the copy-pasteable configurations in docs/client-configuration.md.

Installation profiles

install.sh restores locked environments; it does not use the Linux distribution Python. Run it from the repository root.

Two capabilities need separate provisioning:

• Vision Local backend: bash install.sh --cpu-only installs only the MCP frontend. Build the pinned CUDA llama.cpp server with bash vision-local/install_runtime.sh, provide the documented model and projector files, and verify them with vision_status. See vision-local/README.md.

• Brave Websearch: no Python profile is needed. Install Node.js 22 or newer, set BRAVE_API_KEY in the MCP client's environment, and launch bin/mcp-tools brave-websearch.

The default ASR 1.7B and Vision 9B configurations are 12 GiB reference profiles and are not advertised as 8 GB-compatible. Dedicated 8gb profiles use ASR 0.6B and Vision 4B with bounded runtime settings; real sequential tests observed conservative maxima of 4658 MiB and 5518 MiB across two sequential whole-device runs under an 8000 MiB ceiling. The repository does not currently provide Docker images, non-NVIDIA GPU profiles, or a macOS Python lock target.

MCP client setup

The launcher accepts one of these stable server names:

The transport is standard MCP stdio. A generic command-based client entry is:

{
  "mcpServers": {
    "mcp-tools-format": {
      "command": "/absolute/path/to/mcp-tools/bin/mcp-tools",
      "args": ["format-conversion"]
    }
  }
}

Use absolute paths: desktop clients commonly start servers from a different working directory. Put secrets in the client's environment settings rather than in tracked configuration. Detailed configurations and client-specific file locations are in docs/client-configuration.md.

Real-world workflows

Extract text from a scanned PDF

User request:

Extract the text from this scanned PDF and summarize it.

Recommended routing:

1. Call pdf_to_text first because born-digital PDFs are faster and more accurate to extract directly.

2. If the result is empty or loses required layout, call ocr_document.

3. Read the returned Markdown artifact paths, then summarize their contents.

For a large scan, use ocr_submit, poll with ocr_status, and wait in bounded windows with ocr_wait.

Transcribe a meeting and identify speakers

User request:

Transcribe this meeting recording, identify the speakers, and keep word timestamps.

Call transcribe_diarized. It runs preprocessing, pyannote diarization, timestamped Qwen3-ASR transcription, and speaker/text merging. HF_TOKEN is required. Use transcribe_audio when speaker identity is not needed.

Convert Markdown into a readable PDF

User request:

Convert this Markdown report into a polished PDF using the print theme.

Call markdown_to_pdf with theme="print". Chromium is the default renderer; engine="weasyprint" is available for simpler documents. The tool returns the output path and file size.

Rasterize an SVG safely

User request:

Convert this SVG diagram to a 1600-pixel-wide PNG.

Call svg_to_png with output_width=1600. The CPU-only converter preserves the aspect ratio when only one dimension is supplied, blocks external file and network resources, bounds the requested canvas, and atomically publishes a validated PNG.

Create a model architecture diagram

Call create_diagram(template="stylegan2", output_path="/absolute/path/model.svg") for an editable diagram, compact findings, and an inline preview. Use update_diagram with ID-based changes and the returned revision to revise it. render_diagram remains available for custom specs. The SVG Diagram guide explains mixed text/math labels, semantic themes, ports, groups, and layout. A stdio demo renders three complete examples.

Read a JavaScript-rendered page

User request:

Fetch this page after JavaScript renders and return the article as Markdown.

Call fetch_page. It tries nodriver first and falls back to Playwright. Use cookies or a proxy only when you are authorized to access the target content.

Architecture

flowchart LR
    Client[MCP client] --> Launcher[bin/mcp-tools]
    Launcher --> Diagram["SVG Diagram<br/>stdio / CPU"]
    Launcher --> Format["Format Conversion<br/>stdio / CPU"]
    Launcher --> Browser["Browser Fetch<br/>stdio / local browser"]
    Launcher --> ASR[ASR stdio]
    Launcher --> OCR[OCR stdio]
    Launcher --> Vision[Vision stdio]
    Launcher --> Brave[Brave upstream stdio]
    ASR --> ASRAPI["Loopback FastAPI<br/>Qwen3-ASR / CUDA"]
    OCR --> OCRAPI["Loopback FastAPI<br/>PaddleOCR-VL / CUDA"]
    Vision --> Llama["Loopback llama.cpp<br/>GGUF vision / CUDA"]
    Brave --> BraveAPI[Brave Search API]

ASR and OCR automatically manage their loopback backends. On a 12 GiB GPU they stop competing resident services before loading another model. Vision uses an independent pinned llama.cpp build and three runtime profiles. Keep all heavyweight GPU workloads serialized on limited-VRAM machines. The 8 GB GPU integration harness refuses to start when a heavyweight service port is active and waits for memory release between ASR and Vision. Deliberate overlap tests require an explicit budget above 8000 MiB and are not authorized by the 8 GB profile switch.

Shared model storage

ASR, OCR, Vision, and standalone scripts use MCP_TOOLS_MODEL_DIR, defaulting to this repository's models/ directory. It may be a symlink to a shared store such as ../hf-models/models; a fresh clone can also populate models/ directly. A sibling repository is optional. Models and caches are excluded from Git.

Expanded ASR/OCR snapshots use safetensors/<owner>/<model>; Vision uses gguf/unsloth/<model>. Hub fallback downloads, including ForcedAligner and pyannote dependencies, use .cache/huggingface/hub under the same root. Xet and downstream assets use adjacent xet and assets directories; PaddleX uses .cache/paddlex. Python entrypoints configure these paths before model-library imports, including direct invocations outside an MCP client. Inherited Hub/Transformers cache overrides do not redirect this store; select another store with MCP_TOOLS_MODEL_DIR. HF_HOME, HF_TOKEN_PATH, and credentials retain their existing locations. Run bin/mcp-tools doctor to inspect paths.

Configuration

All variables are optional unless the requirement column says otherwise. Set them in the MCP client process environment.

Backend tuning variables are documented in ocr/README.md, vision-local/README.md, browser-fetch/README.md, and the launcher header in brave-websearch/run.sh.

Troubleshooting

Documentation

Historical hardware measurements and fixture-specific verification reports live under docs/. Treat them as dated evidence for their stated hardware, not universal benchmarks.

Contributing

See CONTRIBUTING.md for profile setup, tests, linting, adding an MCP tool, and the pull-request checklist. Bug reports and feature requests have guided forms under .github/ISSUE_TEMPLATE/.

Run the normal CPU-safe contributor gate with scripts/check.sh. It covers Ruff, shell syntax, CPU tests, all six repository-owned MCP frontends, the PDF-to-text example, documentation links, GitHub YAML, diagnostics, and whitespace checks. GitHub Actions runs this gate on both ubuntu-22.04 and ubuntu-24.04; GPU integration remains opt-in and local.

Good contribution entry points include:

• add a protocol-level test for one existing stdio server (good first issue);

• improve a component's actionable error messages (good first issue);

• add a repo-owned Vision model download helper (help wanted);

• validate and document another Linux NVIDIA GPU/driver combination (help wanted);

• design a CPU or non-NVIDIA backend without changing the stable MCP tool names (help wanted).

Roadmap

These are planned ideas, not current features:

• add an optional, license-aware Vision model download helper;

• add tested CPU or non-NVIDIA alternatives for selected inference services;

• publish profile-specific containers only after GPU and artifact persistence behavior can be tested reproducibly;

• add portable client-config generation and validation.

License

Repository source and documentation are licensed under the MIT License. Runtime dependencies and downloaded models retain their own licenses and usage terms; review them before redistribution.