marginalia

This MCP server exposes a Marginalia-backed search tool that lets you query Marginalia Search from within your MCP apps. It supports configurable search parameters such as the query string, index, and the number of results to return. By calling the marginalia tool with the search action, you get a structured response containing the query, optional licensing information, and an array of results with URLs, titles, and descriptions. The server includes error handling for rate limiting, invalid requests, and network or API-specific errors, helping you gracefully manage quota and connectivity issues. To use it, call the marginalia tool through your MCP runtime with the search action and provide the required query alongside optional parameters like index and count.

Prerequisites:

• Node.js and npm installed on your system
• Access to the project repository and its source code

Installation steps:

1. Install dependencies npm install

2. Build the server (produce the runtime artifacts) npm run build

3. Run the MCP server (example) node build/index.js

4. Optional: set the Marginalia API key in your environment if you have a dedicated key export MARGINALIA_API_KEY=your_api_key_here

5. Verify the server is running and reachable by invoking the MCP tool endpoint in your environment.

Note: Replace paths as needed if your deployment uses a different build output location.

Tips and notes:

• The API key (MARGINALIA_API_KEY) is optional; if omitted, the server will use public access limits by Marginalia. For higher quotas or specialized access, supply your key.
• The default result count is 10 if you do not specify 'count'. You can request 1-100 results per query depending on your plan.
• Rate limiting may return 503 errors; implement retry/backoff logic where appropriate.
• If you need to adjust the search index (as shown in the UI), pass the 'index' parameter to select a specific Marginalia index.
• Ensure that your hosting environment exposes the required environment variables to the Node process at startup.
• If you plan to deploy in containers or serverless environments, map the build/index.js path correctly to your runtime container entry point.