# YaCy peer-to-peer search

> YaCy peer-to-peer search is an open-source MCP server for web search and scraping. Search, crawl and tune ranking on your own YaCy peer-to-peer search peer. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** self-hosted, CLI
- **Website:** https://pad01g.github.io/yacy_search_server/
- **Repository:** https://github.com/pad01g/yacy_search_server/tree/HEAD/mcp
- **MCP Registry name:** io.github.pad01g/yacy-search
- **Categories:** web search and scraping
- **Listing updated:** 2026-11-16

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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

## 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

- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [Firecrawl MCP Server](https://ai-powered.com/mcp/firecrawl-mcp-server): Firecrawl MCP Server is a freemium MCP server for web search and scraping.
- [SearXNG Search](https://ai-powered.com/mcp/searxng-search): SearXNG Search is an open-source MCP server for web search and scraping.
- [NeuralVerge](https://ai-powered.com/mcp/neuralverge): NeuralVerge is an MCP server for web search and scraping.
- [AI-Powered directory](https://ai-powered.com/mcp/ai-powered-directory): AI-Powered directory is a free MCP server for developer tools.
- [Shopify MCP Server (any store)](https://ai-powered.com/mcp/shopify-mcp-server-any-store): Shopify MCP Server (any store) is a paid MCP server for e-commerce.
- [Chanroll: YouTube Channel Video Scraper (Official API)](https://ai-powered.com/mcp/chanroll-youtube-channel-video-scraper-official-api): Chanroll: YouTube Channel Video Scraper (Official API) is a paid MCP server for design and media.
- [Vidvett: YouTube Video Details Scraper (Official API)](https://ai-powered.com/mcp/vidvett-youtube-video-details-scraper-official-api): Vidvett: YouTube Video Details Scraper (Official API) is a paid MCP server for design and media.

---
Source: https://ai-powered.com/mcp/yacy-peer-to-peer-search
