# Kagi Session2API MCP Server **Free Kagi Search MCP server — session tokens, no API key needed** [![PyPI version](https://img.shields.io/pypi/v/kagi-session2api-mcp.svg)](https://pypi.org/project/kagi-session2api-mcp/) [![PyPI downloads](https://img.shields.io/pypi/dm/kagi-session2api-mcp.svg)](https://pypi.org/project/kagi-session2api-mcp/) [![GitHub stars](https://img.shields.io/github/stars/KSroido/Kagi-Session2API-MCP?style=social)](https://github.com/KSroido/Kagi-Session2API-MCP/stargazers) [![GitHub license](https://img.shields.io/github/license/KSroido/Kagi-Session2API-MCP)](LICENSE) [![Python Version](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python)](https://python.org/) **[English](README.md)** | [中文文档](README_ZH.md)
--- > Access Kagi search and summarizer via session tokens — completely free. Works with Claude Desktop, Cursor, Windsurf, Cline, Hermes and any MCP-compatible AI coding assistant/agent. ## ⭐ Star History [![Star History Chart](https://api.star-history.com/svg?repos=KSroido/Kagi-Session2API-MCP&type=Date)](https://star-history.com/#KSroido/Kagi-Session2API-MCP&Date) > **⚠️ EndUser Warning**: This project uses Kagi session tokens to access search and summarizer features without the official paid API. This may violate [Kagi's Terms of Service](https://kagi.com/terms). Potential consequences include account suspension or permanent ban. **Use at your own risk.** The authors assume no liability for any account actions taken by Kagi. > > **⚠️ Security Warning**: Your Kagi session token provides full account access. Treat it like a password. Never share it or commit it to version control. ## 🌟 Features - **Session-based access**: Uses Kagi session tokens instead of the official API ($25/1000 queries) — completely free - **Multi-token pool**: Configure multiple tokens for higher throughput with round-robin rotation - **Per-token rate limiting**: 5 req/s per token with token bucket algorithm - **API-compatible output**: Returns results in the same format as the official `kagimcp` - **Two tools**: `kagi_search_fetch` (web search) and `kagi_summarizer` (URL summarization) - **Firefox UA spoofing**: Mimics a real Firefox browser for session-based access - **Auto-disable expired tokens**: Expired tokens are automatically detected and skipped - **Search operators**: Supports Kagi operators (`site:`, `lang:`, `filetype:`, etc.) ## Compatible Platforms Works with any MCP-compatible client: - [Claude Desktop](https://claude.ai/desktop) - [Cursor](https://cursor.sh) - [Windsurf](https://codeium.com/windsurf) - [Cline](https://cline.bot) - [Hermes Agent](https://github.com/nousresearch/hermes) - Any MCP client supporting `stdio` or `HTTP` transport ## Quick Install (For AI Agents) Just paste this prompt to your AI agent: ``` Install the Kagi Session2API MCP server from https://pypi.org/project/kagi-session2api-mcp/. Then add it to my MCP: `uvx kagi-session2api-mcp` set env KAGI_SESSION_TOKEN to my token (ask me if you don't have it). If I have multiple tokens, use KAGI_SESSION_TOKENS (comma-separated) instead, or create a config file at ~/.config/kagi-session2api-mcp/config.toml with: [kagi] session_tokens = ["TOKEN_1", "TOKEN_2"] summarizer_engine = "cecil" [client] timeout = 30 max_retries = 2 and set env KAGI_SESSION_CONFIG to that path. ``` ## Install Manually ```bash pip install kagi-session2api-mcp ``` Or with `uvx`: ```bash uvx kagi-session2api-mcp ``` ## Configuration ### Option 1: Environment Variable (Single Token) ```json { "mcpServers": { "kagi-session": { "command": "uvx", "args": ["kagi-session2api-mcp"], "env": { "KAGI_SESSION_TOKEN": "YOUR_SESSION_TOKEN_HERE" } } } } ``` ### Option 2: Environment Variable (Multiple Tokens) ```json { "mcpServers": { "kagi-session": { "command": "uvx", "args": ["kagi-session2api-mcp"], "env": { "KAGI_SESSION_TOKENS": "TOKEN_1,TOKEN_2,TOKEN_3" } } } } ``` ### Option 3: Config File (Recommended for Multi-Token) Create `~/.config/kagi-session2api-mcp/config.toml`: ```toml [kagi] session_tokens = [ "YOUR_TOKEN_1_HERE", "YOUR_TOKEN_2_HERE", ] summarizer_engine = "cecil" [client] timeout = 30 max_retries = 2 ``` Then configure: ```json { "mcpServers": { "kagi-session": { "command": "uvx", "args": ["kagi-session2api-mcp"], "env": { "KAGI_SESSION_CONFIG": "/path/to/config.toml" } } } } ``` ## Getting Your Session Token 1. Log in to [kagi.com](https://kagi.com) 2. Go to **Settings → Account → Session Link** 3. Copy the token from the session URL: `https://kagi.com/search?token={THIS_PART}&q=test` 4. Use this token in your configuration ## Usage ### MCP Tools #### `kagi_search_fetch` Search the web using Kagi: ``` Search for "Python async tutorial" ``` Supports Kagi search operators: - `site:github.com` - Restrict to domain - `-site:reddit.com` - Exclude domain - `filetype:pdf` - File type filter - `intitle:python` - Title filter - `lang:zh` - Language filter - `before:2024-01-01` / `after:2024-01-01` - Date filters - `"exact phrase"` - Exact match #### `kagi_summarizer` Summarize any URL: ``` Summarize https://example.com/article ``` Options: - `summary_type`: "summary" (prose) or "takeaway" (bullet points) - `engine`: "cecil" (default), "agnes", "daphne", "muriel" - `target_language`: Language code (e.g., "EN") > ⚠️ The summarizer is experimental — it uses Kagi's internal endpoint which may change. ### Transport Modes **Stdio** (default, for Claude Desktop): ```bash kagi-session2api-mcp ``` **HTTP** (for remote access): ```bash kagi-session2api-mcp --http --host 0.0.0.0 --port 8000 ``` ## Architecture ``` MCP Client → FastMCP Server → TokenPool (round-robin) → httpx.AsyncClient → kagi.com ↓ TokenBucket (5 req/s per token) ↓ Auto-disable expired tokens ``` ## Token Pool Behavior | Config | Rate Limit | Effective Rate | |--------|-----------|----------------| | 1 token | 5 req/s | 5 req/s | | 2 tokens | 5 req/s each | 10 req/s | | N tokens | 5 req/s each | 5×N req/s | When a token expires (detected via 401/403 or redirect to login), it is automatically disabled. Remaining tokens continue serving requests. ## Differences from Official `kagimcp` | Aspect | Official `kagimcp` | `kagi-session2api-mcp` | |--------|-------------------|-------------------| | Authentication | API key ($25/1000) | Session token (free) | | Search endpoint | `/api/v0/search` | `/html/search` (HTML scraping) | | Summarizer | `/api/v0/summarize` | `/mother/summary_labs` (internal) | | Rate limiting | Server-side | Client-side (token bucket) | | `api_balance` | Returns balance | Always `null` | | Cost | Paid | Free (uses existing session) | ## Thank you! Star this repo if you feel it useful, that would help me a lot :) ## License MIT