mcp-ecosia-search by hakandamar - MCP Server

Ecosia Search | MCP Server

Ecosia Search | MCP Server is a lightweight server for querying the Ecosia search engine, designed to be used as an MCP (Model Context Protocol) server for LLMs or other clients. It supports caching via Redis, rate-limiting, and region-specific search.

Features

Fetch search results from Ecosia with region control (Accept-Language header)
Deduplicates URLs
Configurable result limit
Redis caching with 24h TTL by default
Safe handling of large or malicious queries
Returns structured JSON output with query metadata

Installation

You can install and run it locally via npx:

npx mcp-ecosia-search@1.0.0

Or clone the repository:

git clone https://github.com/<your-username>/mcp-ecosia-search.git
cd mcp-ecosia-search
npm install
npm run start

Usage

HTTP API

Endpoint:

POST /search_ecosia
Content-Type: application/json

Payload:

{
    "query": "Ecosia",
    "max_results": 3,
    "region": "en-US"
}

Response:

{
    "results": {
        "search_query": "ecosia",
        "search_region": "en-us",
        "result_count": 10,
        "result_limit": 3,
        "search_results": [
            {
                "title": "Ecosia - the search engine that plants trees",
                "url": "https://www.ecosia.org/",
                "snippet": "Ecosia uses 100% of its profits for the planet and produces enough renewable energy to power all searches twice over."
            },
            {
                "title": "Ecosia: Search to plant trees - Google Play'de Uygulamalar",
                "url": "https://play.google.com/store/apps/details?id=com.ecosia.android&hl=tr",
                "snippet": "Web'de arama yapın. Ağaç dikin. Gezegene güç verin. Ecosia sadece bir arama motorundan daha fazlasıdır; her gün iklim eylemi yapmanın basit bir yoludur."
            },
            {
                "title": "The greenest browser on Earth - Ecosia",
                "url": "https://www.ecosia.org/browser",
                "snippet": "The Ecosia Browser has built-in green features that make it simple to be climate active every day. We produce 25Wh of renewable energy each day you browse."
            }
        ]
    }
}

Notes:

max_results is the number of results returned to the client; the server always fetches the maximum available results internally (up to 10).
region sets the search region (maps to the Accept-Language HTTP header).

MCP Configuration Example

Add the following entry to your mcp_settings.json to use this MCP server:

{
  "ecosia_search": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-ecosia-search@1.0.0"
    ],
    "env": {
      "MCP_API_KEY": "<your_api_key_here>"
    }
  }
}

Notes for LLMs:

You can now call {ecosia_search} in your prompt, and the MCP runtime will handle routing queries to this server.
MCP server internally handles caching, rate-limiting, and region-specific search automatically.

Environment Variables

Variable	Default	Description
`CACHE_TTL_SECONDS`	86400 (24h)	TTL for Redis cache
`REDIS_URL`	`localhost`	Redis host
`REDIS_PORT`	6379	Redis port
`MCP_API_KEY`	N/A	API Key for MCP authentication

Note: MCP_API_KEY system not working for now. I will update this when I get permission from Ecosia.

Development

npm install
npm run start

Code is written in TypeScript.
Uses axios for HTTP requests.
Uses Bottleneck for rate-limiting.
Uses Redis for caching results.

License

Apache License 2.0. See LICENSE for details.