![]()
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
uvx pinrag==0.9.27Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
OPENROUTER_API_KEY=<secret> PINRAG_PERSIST_DIR=<value> claude mcp add io.github.ndjordjevic-pinrag -- uvx pinrag==0.9.27รันในเทอร์มินัล
{ "mcpServers": { "io.github.ndjordjevic-pinrag": { "command": "uvx", "args": [ "pinrag==0.9.27" ], "env": { "OPENROUTER_API_KEY": "<secret>", "PINRAG_PERSIST_DIR": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดPinRAG is for when you want to learn about something and your materials are scattered—PDFs and ebooks, GitHub repos, YouTube videos, Discord discussions, and plain notes. You index those materials into one shared RAG index, then ask questions from Cursor, VS Code (GitHub Copilot), or any MCP-capable assistant and get answers with citations pointing back to pages, timestamps, files, or threads.
Under the hood it is Retrieval-Augmented Generation built with LangChain and exposed as an MCP (Model Context Protocol) server: add documents from the editor, query with natural language, list or remove what you indexed. Supported inputs include PDFs, local text files and directories, Discord exports, YouTube (transcript from URL, playlist, or ID), and GitHub repo URLs. For YouTube you can optionally add vision so on-screen code, diagrams, and UI text are merged with the transcript in the same chunks—see YouTube vision enrichment.
pinrag[vision] + ffmpeg (see YouTube vision enrichment)AMIGA, PI_PICO) for filtered searchquery_tool supports document_id, tag, document_type, PDF page_min/page_max, and response_style (thorough or concise)add_document_tool, query_tool, list_documents_tool, remove_document_tool, set_document_tag_tool, list_collections_tool; optional collection on tools overrides PINRAG_COLLECTION_NAME for that callpinrag://documents (indexed documents) and pinrag://server-config (env vars and config); click in Cursor’s MCP panel to viewuse_pinrag (parameter: request) for querying, indexing, listing, or removing documentsopenrouter/free router), OpenAI, Anthropic, or Cerebras Inference (OpenAI-compatible API); set via PINRAG_LLM_PROVIDER and PINRAG_LLM_MODEL in MCP env or your shellPINRAG_EMBEDDING_MODEL, default nomic-embed-text-v1.5); no API key; first run downloads model weights (~270 MB, cached)ctx.log) plus optional LangSmith tracingAdd PinRAG as an MCP server in your editor. Install uv and ensure uvx is on your PATH—that runs PinRAG from PyPI without a prior pip install.
Cursor: add this under mcpServers in ~/.cursor/mcp.json:
{
"mcpServers": {
"pinrag": {
"command": "uvx",
"args": ["--refresh", "pinrag"],
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key-here",
"PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
}
}
}
}
VS Code (GitHub Copilot): run MCP: Open User Configuration from the Command Palette (or add .vscode/mcp.json in a workspace), then merge this shape—top-level key is servers:
{
"servers": {
"pinrag": {
"command": "uvx",
"args": ["--refresh", "pinrag"],
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key-here",
"PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
}
}
}
}
For clients that speak MCP over HTTP (e.g. pinrag-cli with --server), run:
pinrag server [--host 127.0.0.1] [--port 8765]
This starts a streamable-HTTP MCP endpoint at http://<host>:<port>/mcp. The default pinrag stdio command for editors is unchanged; pinrag server is additive. Connect pinrag-cli with --server http://127.0.0.1:8765/mcp.
Put API keys and any PinRAG settings in the MCP entry’s env block. The server does not load .env files when the editor launches it.
Ask in chat: "Add /path/to/amiga-book.pdf with tag AMIGA", "Index https://youtu.be/xyz and ask what it says", "Index https://github.com/owner/repo and ask about the codebase", or "Index https://docs.langchain.com/ and summarize its memory APIs". The AI will invoke the tools for you. Citations show page numbers for PDFs, timestamps (e.g. t. 1:23) for YouTube, document names for plain text and Discord exports, chunk index labels for GitHub, and source URLs for web documentation.
Index a repo with add_document_tool and a URL in paths, e.g. https://github.com/owner/repo, https://github.com/owner/repo/tree/branch, or github.com/owner/repo (scheme optional).
GitHub-only options: branch, include_patterns / exclude_patterns — defaults already favor common text and source files and skip bulky artifacts; use patterns when you need files outside that set. Files over PINRAG_GITHUB_MAX_FILE_BYTES (default 512 KiB) are skipped.
Auth: Set GITHUB_TOKEN in MCP env (or the shell) for private repos or fewer rate-limit hits on big indexes; small public runs often work without it. Use a classic or fine-grained PAT with repo read access; there is no OAuth in PinRAG.
Point add_document_tool at any documentation site URL, e.g. https://docs.langchain.com/, https://docs.crewai.com/, or https://picocomputer.github.io/. PinRAG discovers pages via (in order) llms.txt / llms-full.txt (Mintlify-style), sitemap.xml (including robots.txt Sitemap: hints and nested sitemap indexes), then a scoped BFS crawl from the seed URL.
Scope: exact host match (no subdomains) plus path prefix derived from the seed — e.g. https://docs.example.com/guide/ only indexes pages under /guide/. Use the site root URL to capture the full docs tree.
Extraction: text/markdown responses (from llms.txt fast paths) pass through; HTML runs through trafilatura with a BeautifulSoup + markdownify fallback that scopes to <main> / <article> / [role=main].
Limits & politeness: controlled by PINRAG_WEB_MAX_PAGES (default 200), PINRAG_WEB_MAX_DEPTH (5), PINRAG_WEB_MAX_PAGE_BYTES (1 MiB), PINRAG_WEB_CONCURRENCY (4), PINRAG_WEB_RATE_LIMIT_PER_HOST (2.0/sec), and PINRAG_WEB_RESPECT_ROBOTS (true). Some sites (e.g. Cloudflare-protected pages) may return 403 to pure-Python clients; that's a known limitation.
Citations: web chunks carry a source_url metadata field; answers cite per-page URLs, and the document_id is <host><path_prefix> so remove_document_tool / set_document_tag_tool operate on the whole site at once.
Transcript-heavy indexing—especially from cloud or high-volume IPs—may return errors like "YouTube is blocking requests from your IP". Point youtube-transcript-api at a proxy via MCP env (or your shell):
PINRAG_YT_PROXY_HTTP_URL=http://user:[email protected]:80
PINRAG_YT_PROXY_HTTPS_URL=http://user:[email protected]:80
PINRAG_YT_PROXY_* affects transcript fetches only; yt-dlp steps (titles, playlists) do not use it. Residential or rotating proxies usually fare better than raw datacenter IPs.
When some paths fail (e.g. a few videos in a playlist), add_document_tool includes fail_summary with counts keyed by blocked, disabled, missing_transcript, and other.
Default indexing is transcript-only. Set PINRAG_YT_VISION_ENABLED=true to add vision captions for on-screen content, time-aligned with the transcript and chunked with metadata such as has_visual, frame_count, and visual_source.
PINRAG_YT_VISION_PROVIDER:
openai (default) or anthropic: yt-dlp download → scene-based frames → one multimodal call per frame. Needs pinrag[vision], ffmpeg/ffprobe on PATH, and OPENAI_API_KEY or ANTHROPIC_API_KEY (install the extra in the same env as pinrag, e.g. uv sync --extra vision or pip install 'pinrag[vision]').openrouter: one OpenRouter request per video via video_url (default google/gemini-2.5-flash). OPENROUTER_API_KEY only—no download, ffmpeg, or pinrag[vision]; choose a video-capable model if you override PINRAG_YT_VISION_MODEL.Ops: Re-index after changing vision settings. For openai/anthropic, tune cost and timeouts with PINRAG_YT_VISION_MAX_FRAMES and optional PINRAG_YT_VISION_IMAGE_DETAIL=high (clearer small text, more tokens). MCP stdio: yt-dlp progress goes to stderr so stdout stays JSON-clean. Downloading video can breach YouTube ToS or local rules—your call. Docker: build with BUILD_WITH_VISION=1 for ffmpeg + pinrag[vision] (see Dockerfile).
pinrag not found: MCP inherits your login PATH. After pipx or uv tool install, restart the editor and confirm which pinrag.PINRAG_PERSIST_DIR: Use a stable absolute path in MCP env (e.g. ~/.pinrag/chroma_db) so the vector store does not depend on the server process cwd.pinrag[rerank] in the same tool env (pipx install 'pinrag[rerank]' / uv tool install 'pinrag[rerank]'); tunables are in Configuration.pinrag://server-config: MCP Resources → this URI for PINRAG_VERSION, effective LLM/embeddings/chunking, and API key set / not set status.The pinrag://server-config MCP resource prints PINRAG_VERSION (package version, not an env var you set) and effective values for the variables below, plus which API keys are set. Use the table as the full env reference.
Environment variables:
Re-indexing when changing embedding model: Changing
PINRAG_EMBEDDING_MODELrequires re-indexing; vector dimensions must match the model used at index time (including indexes created under an older default embedding).Re-indexing when enabling parent-child: Setting
PINRAG_USE_PARENT_CHILD=truerequires re-indexing; the new structure (child chunks in Chroma, parent chunks in docstore) is created only during indexing for supported document types (not plain.txt).Re-indexing when toggling YouTube vision: Turning
PINRAG_YT_VISION_ENABLEDon or off, changingPINRAG_YT_VISION_PROVIDER, or changing vision model /PINRAG_YT_VISION_IMAGE_DETAIL/ frame limits, requires re-indexing affected YouTube documents for chunks to reflect the new behavior.
For query performance metrics (latency, timing, token usage) and debugging, use LangSmith. Set LANGSMITH_TRACING=true and LANGSMITH_API_KEY in MCP env or your shell; optionally set LANGSMITH_PROJECT (see table above). If your LangSmith workspace is in the EU region (you use eu.smith.langchain.com in the browser), you must also set LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com; without it, traces may not show up in the EU deployment. US-region accounts use the default API host and do not need LANGSMITH_ENDPOINT. See notes/langsmith-setup.md for more detail.
For MCP-side introspection, set PINRAG_VERBOSE_LOGGING=true to surface detailed phase events in notifications/message (e.g., YouTube transcript load, whether vision runs, and chunk upsert milestones).
Vector dimension is fixed per Chroma collection and must match the PINRAG_EMBEDDING_MODEL used when chunks were written. The default id nomic-embed-text-v1.5 is a 768-d Nomic model; another PINRAG_EMBEDDING_MODEL value may imply a different size—check that model’s documentation.
PINRAG_COLLECTION_NAME defaults to pinrag. Do not change PINRAG_EMBEDDING_MODEL for an existing collection without re-indexing into a new collection (or wiping the old one); otherwise adds/queries can fail with embedding dimension errors.PINRAG_EMBEDDING_MODEL + PINRAG_COLLECTION_NAME (+ PINRAG_PERSIST_DIR if you isolate stores) for each index. To query a collection, set the same env values you used when indexing it. You can index the same sources again under another pair (change env, restart MCP if needed, run add_document_tool).config.get_persist_dir() and config.get_collection_name() by default; optional collection on a tool call overrides the collection name for that request. list_collections_tool lists collection names in the configured persist directory (optional persist_dir override).Tools, prompt, and read-only resources from the pinrag MCP server (FastMCP("PinRAG")). Tool results are JSON objects that always include _server_version; with PINRAG_VERBOSE_LOGGING=true they may include _verbose_log.
add_document_tool returns indexed, failed, counts, persist_directory, collection_name, and fail_summary when any path failed. query_tool returns answer and sources (each entry: document_id, page—PDF page, often 0 for non-PDF—plus optional start in seconds for YouTube).
query_toolNatural-language question; optional filters narrow retrieval ("" / omit when unused):
Filters can be combined. The sources list uses page for PDFs and start (seconds) for YouTube; answers may show t. M:SS labels derived from start. GitHub citations use chunk-index-style p. N labels in the answer text. Web docs sources carry a per-page source_url.
Example: "What is OpenOCD? In the Pico doc, pages 16–17 only" → query_tool(query="What is OpenOCD?", document_id="RP-008276-DS-1-getting-started-with-pico.pdf", page_min=16, page_max=17).
add_document_toolIndex locals (PDF, plain or Discord .txt, directories), YouTube (video URL, playlist URL, or bare id), GitHub URLs (scheme optional), or web documentation sites (any http(s) URL). paths batches work items; one failed path does not roll back others. Persists to PINRAG_PERSIST_DIR / PINRAG_COLLECTION_NAME only (no MCP parameters for those).
list_documents_toolReturns documents, total_chunks, persist_directory, collection_name, and document_details (tags, titles, counts, aggregated bytes when present, upload_timestamp, etc.). If tag is set, total_chunks counts only chunks with that tag (not the whole collection).
remove_document_toolDeletes every chunk for document_id. Accepts the exact ref from list_documents_tool, the list title, or a unique PDF filename stem.
set_document_tag_toolSets or replaces the tag on every indexed chunk for one document. Useful to add or correct a tag after indexing, without re-indexing. Same document-targeting rules as remove_document_tool.
use_pinragBuilt-in routing blurb: request is interpolated as the first line; the rest lists when to use each tool and their parameters (matches use_pinrag in server.py). Listed wherever the client exposes MCP prompts (e.g. Cursor).
From the repo root, install dev extras (e.g. uv sync --extra dev).
Fast (no integration):
uv run pytest tests/ -q -m "not integration"
Skips anything marked integration in pyproject.toml (network, API keys, optional assets, MCP stdio). Any test that uses the sample_pdf_path fixture gets that marker automatically in tests/conftest.py, so the sample PDF under data/pdfs/ is only needed for the full run.
Full suite:
uv run pytest tests/ -q
Secrets: For MCP stdio tests, the subprocess env starts from your shell, then any missing OPENAI_API_KEY / ANTHROPIC_API_KEY are filled from tests/.mcp_stdio_integration.env (copy from tests/mcp_stdio_integration.env.example; only those keys are read from the file—already-set env wins). Override the file with PINRAG_MCP_ITEST_ENV_FILE. After merge, test_mcp_stdio_repo.py requires OPENAI_API_KEY, and PINRAG_LLM_PROVIDER must pass its credential check (e.g. export OPENROUTER_API_KEY when using OpenRouter). test_mcp_stdio_pypi.py also requires a working OpenAI key.
PDF / stdio: Default PDF is data/pdfs/sample-text.pdf (not in git). Override with PINRAG_MCP_ITEST_PDF / PINRAG_MCP_ITEST_QUERY. Stdio tests need uv on PATH, or set PINRAG_TEST_UV to the binary path.
PyPI MCP test: Marked pypi_mcp; skip with -m "not pypi_mcp" or PINRAG_MCP_ITEST_SKIP_PYPI=1. Pin the install with PINRAG_MCP_ITEST_PYPI_SPEC (default pinrag = latest on PyPI).
Verbose: --log-cli-level=INFO.
The data/ directory is gitignored—create data/pdfs/ (and similar) locally; nothing under data/ is committed.
MIT License. Full text in LICENSE.
MCP RAG: index PDFs, repos, YouTube, Discord, text; optional YouTube vision; query with citations.
{ "mcpServers": { "io.github.ndjordjevic-pinrag": { "command": "uvx", "args": [ "pinrag==0.9.27" ], "env": { "OPENROUTER_API_KEY": "<secret>", "PINRAG_PERSIST_DIR": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: OPENROUTER_API_KEY, PINRAG_PERSIST_DIR
PinRAG ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-10 MCP RAG: index PDFs, repos, YouTube, Discord, text; optional YouTube vision; query with citations.