{"id":50307257,"url":"https://github.com/hra42/kagi-search-mcp","last_synced_at":"2026-05-28T17:30:41.757Z","repository":{"id":358342656,"uuid":"1239800042","full_name":"hra42/kagi-search-mcp","owner":"hra42","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-16T22:13:07.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T23:39:47.474Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hra42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T13:03:29.000Z","updated_at":"2026-05-16T22:13:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hra42/kagi-search-mcp","commit_stats":null,"previous_names":["hra42/kagi-search-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hra42/kagi-search-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fkagi-search-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fkagi-search-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fkagi-search-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fkagi-search-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hra42","download_url":"https://codeload.github.com/hra42/kagi-search-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fkagi-search-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33619965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-28T17:30:39.081Z","updated_at":"2026-05-28T17:30:41.750Z","avatar_url":"https://github.com/hra42.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kagi-search-mcp\n\nA local [MCP](https://modelcontextprotocol.io) server that exposes the [Kagi](https://kagi.com) API as tools, built in Go on top of:\n\n- [`github.com/hra42/kagi-go-sdk`](https://github.com/hra42/kagi-go-sdk)\n- [`github.com/modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk)\n\nTransports: **stdio** (default) and **Streamable HTTP** (via `--http`).\n\n## Install (Claude Desktop, one-click)\n\n1. Download the latest `.mcpb` for your platform from the [Releases page](https://github.com/hra42/kagi-search-mcp/releases/latest):\n   - macOS Apple Silicon: `kagi-search-mcp-vX.Y.Z-darwin-arm64.mcpb`\n   - macOS Intel:         `kagi-search-mcp-vX.Y.Z-darwin-amd64.mcpb`\n   - Linux x86_64:        `kagi-search-mcp-vX.Y.Z-linux-amd64.mcpb`\n   - Windows x86_64:      `kagi-search-mcp-vX.Y.Z-windows-amd64.mcpb`\n2. Double-click the file. Claude Desktop shows an install dialog.\n3. Paste your Kagi API key (get one at https://kagi.com/settings?p=api) when prompted.\n4. Done — the search tools and prompts appear in the next conversation.\n\n\u003e **Note:** Claude Desktop will show an \"unverified publisher\" warning on install. This is normal — the bundle is not code-signed. Verify the download came from this repo's official releases page.\n\nFor other MCP clients (Claude Code, VS Code Copilot, custom integrations), see [Manual install](#manual-install) below.\n\n## Requirements\n\n- Go 1.26+\n- A Kagi API key — get one at https://kagi.com/settings?p=api\n\n## Build\n\n```bash\ngo mod tidy\ngo build -o kagi-search-mcp .\n```\n\n## Manual install\n\nFor clients that don't support MCPB bundles, or to run the server from source: edit the client's MCP server config. For Claude Desktop, that's `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"kagi\": {\n      \"command\": \"/absolute/path/to/kagi-search-mcp\",\n      \"env\": { \"KAGI_API_KEY\": \"sk-...\" }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The `kagi_search` and `kagi_extract` tools should appear.\n\n## HTTP transport\n\nRun the server as an HTTP service with Streamable HTTP transport:\n\n```bash\nKAGI_API_KEY=sk-... \\\nMCP_AUTH_TOKEN=$(openssl rand -hex 32) \\\n./kagi-search-mcp --http 127.0.0.1:8080\n```\n\nFlags:\n\n- `--http \u003caddr\u003e` — listen address (e.g. `:8080`, `127.0.0.1:8080`). Omit to use stdio.\n- `--http-path \u003cpath\u003e` — URL path for the MCP endpoint (default `/mcp`).\n\nRequired env:\n\n- `KAGI_API_KEY` — Kagi API key (same as stdio mode).\n- `MCP_AUTH_TOKEN` — shared bearer token. Clients must send `Authorization: Bearer \u003ctoken\u003e`. Requests without it get `401`.\n\nOptional env:\n\n- `LOG_LEVEL` — `debug` \\| `info` (default) \\| `warn` \\| `error`. Logs are emitted as structured JSON on stderr.\n- `MCP_RATE_RPS` — per-remote-IP refill rate for the token-bucket rate limiter (default `5`).\n- `MCP_RATE_BURST` — per-remote-IP burst capacity (default `20`). Excess requests get `429` with `Retry-After: 1`.\n- `KAGI_SNIPPET_MAX` — max snippet length in the formatted **detailed** search markdown (default `300`).\n- `KAGI_MAX_OUTPUT_CHARS` — global cap on the formatted markdown returned by either tool (default `100000` ≈ 25k tokens). When exceeded, the output is truncated and an actionable footer is appended telling the agent how to recover.\n\nBuilt-in endpoints:\n\n- `GET /healthz` — always `200 OK` (no auth). For liveness probes.\n- `GET /readyz` — `200` when the server has its API key configured, `503` otherwise. For readiness probes.\n- `GET /\u003chttp-path\u003e` and `POST /\u003chttp-path\u003e` — MCP Streamable HTTP, bearer-auth required.\n\nEvery authenticated request carries an `X-Request-ID` header (echoed from the client or generated server-side) and is logged with method, path, status, duration, and remote IP. Query strings and the `Authorization` header are deliberately **not** logged.\n\nQuick check:\n\n```bash\ncurl -X POST http://127.0.0.1:8080/mcp \\\n  -H \"Authorization: Bearer $MCP_AUTH_TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"0\"}}}'\n```\n\n### Security model\n\n- **Transport.** There's no TLS — bind to `127.0.0.1` for local use, or front the server with a reverse proxy (Caddy, nginx) that terminates TLS.\n- **Auth.** A single shared bearer token (`MCP_AUTH_TOKEN`) gates the MCP endpoint. This is appropriate for trusted single-tenant deployments. For multi-tenant or production use, terminate **OAuth 2.1** at a gateway in front of this server (the [MCP spec](https://modelcontextprotocol.io) standardizes OAuth 2.1 for HTTP transports). Rotate the token like any other credential.\n- **Rate limiting.** A per-IP token bucket protects the upstream Kagi API and the local process; tune via `MCP_RATE_RPS` / `MCP_RATE_BURST`.\n- **Audit logging.** All requests are logged as structured JSON. PII-adjacent fields (`Authorization`, query string, request body) are intentionally omitted; if your environment requires fuller audit trails, capture them at the reverse proxy layer.\n- **Tool annotations.** Both tools advertise `readOnlyHint: true` and `destructiveHint: false` so MCP clients can apply least-privilege policies.\n\n## Design notes\n\nThe server is built around the recommendations from Anthropic's [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents) and [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) — most importantly that **output tokens are the scarce resource** and tool responses should help the agent pick the next action.\n\n- **Two tools, not ten.** `kagi_search` returns ranked URLs; `kagi_extract` reads their contents. No 1:1 wrappers around every Kagi endpoint.\n- **`response_format: \"concise\"` is the default.** Concise mode returns the top 5 hits per bucket with titles + URLs only — no snippets. This is the right default when the agent's next step is to extract one of those URLs anyway. Pass `response_format: \"detailed\"` for the full snippet view.\n- **Field filtering.** `fields: [\"web\", \"news\"]` restricts the response to those buckets only.\n- **Per-URL truncation on extract.** `max_chars: 4000` caps each page's markdown when scanning many pages. The structured `items[].markdown` preserves the full content so downstream code (or a follow-up call) can read more without re-fetching.\n- **Global output cap.** Every response is truncated to `KAGI_MAX_OUTPUT_CHARS` characters (default 100k ≈ 25k tokens, matching Claude Code's default). When truncated, the footer tells the agent how to recover (narrow the query, use concise mode, extract URLs one at a time, etc.).\n- **Next-step hints.** Every response ends with a short prose hint pointing at the natural follow-up tool call. No silent dead ends.\n- **Server `instructions`.** The Initialize response includes a short workflow primer that MCP clients (Claude Code, Claude Desktop, VS Code Copilot) inject into the system prompt at session start.\n- **Errors are actionable.** Kagi 401/429/400/5xx are surfaced as `IsError: true` with a recovery hint (retry-after duration, \"verify the key\", \"omit the parameter\", etc.). Per-URL extract failures are correlated back to the requested URL and tagged with code-specific hints (`extract.timeout` → \"retry alone with a higher timeout\").\n\n## Tools\n\n### `kagi_search`\n\n| Field | Type | Default | Notes |\n|---|---|---|---|\n| `query` | string (required) | — | Supports Kagi operators (`site:`, `intitle:`, quoted phrases) |\n| `limit` | int 1–100 | Kagi's choice | Results per page |\n| `page` | int 1–10 | 1 | Pagination |\n| `safe_search` | `\"on\"` \\| `\"off\"` | account default | |\n| `workflow` | `search` \\| `images` \\| `videos` \\| `news` \\| `podcasts` | `search` | |\n| `response_format` | `\"concise\"` \\| `\"detailed\"` | `\"concise\"` | Concise = titles+URLs only, top 5 per bucket |\n| `fields` | string[] | all | Buckets to keep: `web`, `news`, `image`, `video`, `podcast`, `direct_answer`, `infobox`, `related_search` |\n\nReturns markdown text + a structured `results` array with `type`, `title`, `url`, `snippet`, `time`. The structured array always includes the full snippet even in concise mode.\n\n### `kagi_extract`\n\n| Field | Type | Default | Notes |\n|---|---|---|---|\n| `urls` | string[] (required) | — | 1–10 HTTPS URLs |\n| `timeout` | number | server default | Overall timeout in seconds (0.5–10) |\n| `max_chars` | int ≥ 0 | 0 = unlimited | Per-URL markdown truncation in the formatted text |\n\nReturns concatenated markdown + a structured `items` array. Each item carries either `markdown` (full, never truncated in the structured field) or an `error`. Per-URL failures don't fail the call.\n\n## Prompts\n\nThe server also exposes MCP prompts — pre-built templates that compose `kagi_search` and `kagi_extract` into common research workflows. In compatible clients (Claude Desktop, Claude Code, VS Code Copilot) they appear in the slash-prompt / prompt-picker menu. Each prompt returns a single user message that instructs the LLM which tools to call and how to format the answer.\n\n| Prompt | Arguments | What it does |\n|---|---|---|\n| `research` | `topic` (required), `depth` (`shallow` \\| `deep`, default `deep`) | Search → pick 3–5 authoritative URLs → extract → cited brief with TL;DR, findings, sources, open questions |\n| `fact-check` | `claim` (required) | Neutral search + counter-position search → 3–5 independent sources → extract → verdict block + supporting/contradicting evidence + confidence |\n| `compare-sources` | `topic` (required), `perspectives` (int 2–5, default 3) | Surface N distinct viewpoints, one source each, then a neutral synthesis of the actual axis of disagreement |\n| `find-primary-sources` | `topic` (required) | Serial searches biased toward originals (`site:gov/edu/org`, `filetype:pdf`, official statements); returns a curated list with provenance notes |\n| `summarize-url` | `url` (required, https), `focus` (optional) | Extract a single page in full → TL;DR + outline + key facts + caveats, optionally weighted toward a focus |\n\nPrompts make no Kagi API calls themselves — they only emit text that guides the LLM to use the existing tools.\n\n## Development\n\n```bash\ngo test -race ./...\ngo vet ./...\ngolangci-lint run   # optional, mirrors CI\n```\n\nCI runs `vet`, `test -race`, `golangci-lint`, and `build` on every push and PR (see `.github/workflows/ci.yml`).\n\n## Troubleshooting\n\n- **Server exits immediately with \"KAGI_API_KEY environment variable is required\"** — set the env var in the MCP client config.\n- **401 Unauthorized** — invalid or revoked key.\n- **429 Rate limited** — the SDK retries with backoff; persistent 429s mean the account quota is exhausted.\n\n## License\n\nUnlicense (public domain).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhra42%2Fkagi-search-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhra42%2Fkagi-search-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhra42%2Fkagi-search-mcp/lists"}