Skip to content
MCP server

YaCy peer-to-peer search

Search, crawl and tune ranking on your own YaCy peer-to-peer search peer

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
self-hosted, CLI
Runs
Locally
Version
1.0.0
Listing updated
1 day ago

About YaCy peer-to-peer search

YaCy peer-to-peer search is an open-source MCP server for web search and scraping. It runs locally on your machine and is started by your AI client.

There is no central search service behind this server: it talks over HTTP to a YaCy peer that you run yourself, usually in Docker, and searches the peer-to-peer network that peer belongs to. No search API or key is involved. It was written for an experimental improved-search fork of YaCy, where results carry author-signature verdicts and tags, and the search, crawl, status and settings tools also work with upstream YaCy.

Beyond searching, an agent can start crawls with depth, range and per-host page limits, check index counts and crawl queues, list connected peers and read or change a short allow-list of ranking settings. Crawl, settings and delete operations need the peer's administrator password, and crawling private or loopback addresses and changing trust filters are off unless switched on by environment variables.

The fork's own page calls itself an experiment, unaffiliated with the YaCy project and deliberately incompatible with the public YaCy network. The image ships with a default admin login that the README says to change before connecting.

Install

Run in a terminal

claude mcp add yacy-search --env YACY_URL='<YACY_URL>' --env YACY_ADMIN_PASSWORD='<YACY_ADMIN_PASSWORD>' -- docker run -i --rm -e YACY_URL -e YACY_ADMIN_PASSWORD ghcr.io/pad01g/yacy-search-mcp:1.0.0

Add to claude_desktop_config.json

{
  "mcpServers": {
    "yacy-search": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YACY_URL",
        "-e",
        "YACY_ADMIN_PASSWORD",
        "ghcr.io/pad01g/yacy-search-mcp:1.0.0"
      ],
      "env": {
        "YACY_URL": "<YACY_URL>",
        "YACY_ADMIN_PASSWORD": "<YACY_ADMIN_PASSWORD>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "yacy-search": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YACY_URL",
        "-e",
        "YACY_ADMIN_PASSWORD",
        "ghcr.io/pad01g/yacy-search-mcp:1.0.0"
      ],
      "env": {
        "YACY_URL": "<YACY_URL>",
        "YACY_ADMIN_PASSWORD": "<YACY_ADMIN_PASSWORD>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "yacy-search": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YACY_URL",
        "-e",
        "YACY_ADMIN_PASSWORD",
        "ghcr.io/pad01g/yacy-search-mcp:1.0.0"
      ],
      "env": {
        "YACY_URL": "<YACY_URL>",
        "YACY_ADMIN_PASSWORD": "<YACY_ADMIN_PASSWORD>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "yacy-search": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YACY_URL",
        "-e",
        "YACY_ADMIN_PASSWORD",
        "ghcr.io/pad01g/yacy-search-mcp:1.0.0"
      ],
      "env": {
        "YACY_URL": "<YACY_URL>",
        "YACY_ADMIN_PASSWORD": "<YACY_ADMIN_PASSWORD>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "yacy-search": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YACY_URL",
        "-e",
        "YACY_ADMIN_PASSWORD",
        "ghcr.io/pad01g/yacy-search-mcp:1.0.0"
      ],
      "env": {
        "YACY_URL": "<YACY_URL>",
        "YACY_ADMIN_PASSWORD": "<YACY_ADMIN_PASSWORD>"
      }
    }
  }
}

Configuration

  • YACY_URLBase URL of your YaCy peer as seen from the MCP server container, e.g. http://yacy:8090 on a shared Docker network (docker run --network ...), or http://host.docker.internal:8090Required
  • YACY_ADMIN_USERYaCy administrator account, needed for crawling and settings
  • YACY_ADMIN_PASSWORDYaCy administrator password; without it crawl, settings and the index counts of index_status are not available
  • YACY_CRAWL_ALLOW_PRIVATE1 lets crawl reach loopback and private addresses (intranets); off by default
  • YACY_ALLOW_TRUST_SETTINGS1 lets set_ranking_setting change the trust filter settings (acceptUnverified, excludeTags); off by default

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

search_web
Full-text search, optionally across connected peers
crawl_site
Start a crawl of a site
get_index_status
Indexed documents, crawl queues and peer status
list_peers
Connected peers with reach and tags
get_ranking_settings
Ranking and filtering settings with meanings
set_ranking_setting
Change one allow-listed ranking setting
control_crawl
Control running crawls
delete_document
Delete a document from the index

What it does

Peer-to-peer search
search_web queries your peer and can ask connected peers too.
Site crawling
crawl_site starts a crawl with depth, range and max pages per host.
Index status
get_index_status reports documents, crawl queues and peer type.
Peer listing
list_peers shows connected peers with signed seed, reach and tags.
Ranking settings
Read all ranking settings and change an allow-listed few.
Guarded admin actions
Crawl, settings and deletion need the admin password; private-address crawling is opt-in.

Good for

  • Search the web from an agent without any search API key
  • Index a documentation site on a private YaCy peer
  • Check why a crawl is paused or a peer has no public address
  • Experiment with ranking settings and compare results

Pricing

Open source

Free; you run your own YaCy peer

Prices change. Check pad01g.github.io before you buy.

YaCy peer-to-peer search FAQ

Do I need an API key?

No. It uses your own YaCy peer instead of a search API.

How do I run it?

The README shows a Docker image run over stdio next to a YaCy peer on a shared Docker network, or Node 24 without Docker.

Which actions need the admin password?

crawl_site, control_crawl, delete_document and set_ranking_setting are refused without it.

Does it work with regular YaCy?

Search, crawl, status and settings also work with upstream YaCy, though it targets the improved-search fork.

Is YaCy peer-to-peer search free?

Yes. YaCy peer-to-peer search is open source, so you can use and self-host it for free.

How do I add YaCy peer-to-peer search to Claude Code?

Run this command in your terminal: claude mcp add yacy-search --env YACY_URL='<YACY_URL>' --env YACY_ADMIN_PASSWORD='<YACY_ADMIN_PASSWORD>' -- docker run -i --rm -e YACY_URL -e YACY_ADMIN_PASSWORD ghcr.io/pad01g/yacy-search-mcp:1.0.0

What are the best alternatives to YaCy peer-to-peer search?

The closest alternatives to YaCy peer-to-peer search are Scrapling MCP Server, Firecrawl MCP Server, SearXNG Search, NeuralVerge and AI-Powered directory.

Alternatives to YaCy peer-to-peer search

  1. MCP server for AI clients to scrape sites with HTTP and stealth browser sessions

    Runs locally
    • 17 tools
    • Open source
    • 104K GitHub stars
    • Web search and scraping
  2. MCP server that lets AI agents search, scrape and interact with web pages

    • 3 tools
    • Remote
    • Freemium
    • 7.8K GitHub stars
    • Web search and scraping
  3. SearXNG Search

    MCP server

    MCP server for web search and page reading through a SearXNG instance

    Runs locally
    • 3 tools
    • Open source
    • 1.4K GitHub stars
    • Web search and scraping
  4. NeuralVerge

    MCP server

    Structured, source-tagged business and people data from 300+ sources for agents

    • 200 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Web search and scraping
  5. Search AI tools, agents and MCP servers and get install configs from inside your AI assistant.

    • 4 tools
    • Remote
    • Free
    • Developer tools
  6. Hosted MCP server that returns any Shopify store's products, prices and stock

    Not checked yet
    • 4 tools
    • Remote
    • Paid
    • E-commerce