Kagi FastMCP Server 🔍

A powerful FastMCP (Model Context Protocol) server for searching Kagi.com and fetching web pages with persistent authentication and browser automation. Perfect for Claude Desktop, Cursor, and other MCP clients.

🎯 Why This Implementation?

Key Innovation: Single Sign-On with Persistent Cookies

• ✅ Authenticate once, cookies persist for ~30 days
• ✅ No re-authentication on server restarts
• ✅ Perfect for MCP clients that frequently start/stop servers
• ✅ Built on pure FastMCP 2.0 for optimal performance

✨ Key Features

• 🔐 Single Sign-On: Authenticate once, use for weeks
• 💾 Persistent Cookie Storage: Saves to ~/.kagi_mcp/cookies.json
• 🚀 FastMCP Native: Built specifically for MCP clients
• 🌐 Two Powerful Tools:
  • search: Search Kagi.com with full results
  • fetch_webpage: Fetch and convert pages to markdown
• 📊 Progress Reporting: Real-time updates via MCP Context
• 🔒 Bearer Token Auth: Secure client authentication
• 🏗️ Modular Architecture: Clean, maintainable codebase
• 🧪 Comprehensive Testing: Unit + integration tests
• 💳 No API Credits: Uses your Kagi Professional subscription

🚀 Quick Start

Prerequisites

# Install dependencies
uv sync

# Install Playwright browsers
uv run playwright install chromium

Environment Setup

# Required
export KAGI_TOKEN="your_kagi_token"        # From kagi.com
export ACCESS_TOKEN="your_access_token"    # For MCP client auth

# Optional  
export KAGIAPI_PORT=8000                   # Default port
export LOGGING_LEVEL=INFO                  # Log level

Run the Server

# HTTP server (for testing)
uv run python run_server.py

# MCP server (for Claude Desktop/Cursor)
uv run python main.py --stdio

📖 Usage

With FastMCP Client

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

async with Client(
    "http://localhost:8000/mcp",
    auth=BearerAuth(token="your_access_token")
) as client:
    # Search Kagi
    results = await client.call_tool("search", {
        "query": "python fastmcp tutorial"
    })
    print(f"Found {results.structured_content['total_found']} results")
    
    # Fetch webpage
    content = await client.call_tool("fetch_webpage", {
        "url": "https://example.com"
    })
    print(f"Fetched {len(content.structured_content)} characters")

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kagi-search": {
      "command": "uv",
      "args": ["run", "python", "/path/to/kagiapi/main.py", "--stdio"],
      "env": {
        "KAGI_TOKEN": "your_kagi_token",
        "ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

With Cursor

1. Install as MCP server in Cursor settings
2. Use the tools directly in your coding workflow

🏗️ Architecture

kagiapi/
├── services/
│   └── browser.py          # Cookie-persistent browser service  
├── models/
│   └── types.py            # Pydantic data models
├── auth/
│   └── providers.py        # Bearer token authentication
├── tests/
│   ├── test_integration.py # Comprehensive test suite
│   └── auth_helper.py      # Interactive auth for tests
├── server.py               # FastMCP server with tools
├── main.py                 # Entry point (supports --stdio)
├── run_server.py           # HTTP server runner
└── README_FASTMCP.md       # Detailed technical docs

🔐 Authentication Flow

1. First Run: Server authenticates with Kagi, saves cookies to disk
2. Subsequent Runs: Loads existing cookies, validates them
3. If Valid: Skips authentication entirely (no browser launch needed!)
4. If Expired: Re-authenticates automatically (rare, ~30 days)

Cookie Storage: ~/.kagi_mcp/cookies.json (secure permissions: 600)

🧪 Testing

# Test all components
uv run python test_initialization.py

# Integration tests (requires auth)
uv run python tests/auth_helper.py      # First time only
uv run python tests/test_integration.py

# Test live server
uv run python run_server.py &          # Start server
uv run python test_live_server.py      # Test client

🆚 FastAPI vs FastMCP Comparison

Feature	Original FastAPI	New FastMCP
Authentication	Every server start	Once every ~30 days
Cookie Storage	In-memory only	Persistent to disk
Architecture	Monolithic	Modular services
MCP Features	Basic	Full Context/Progress
Framework	FastAPI + custom MCP	Pure FastMCP 2.0
Client Support	HTTP only	MCP native
Testing	Basic	Comprehensive

🔧 Configuration

Environment Variables

• KAGI_TOKEN (required): Your Kagi authentication token
• ACCESS_TOKEN (required): Bearer token for MCP client auth
• KAGIAPI_PORT (optional): HTTP server port (default: 8000)
• LOGGING_LEVEL (optional): Log level (default: INFO)

Cookie Management

• Location: ~/.kagi_mcp/cookies.json
• Permissions: 600 (user read/write only)
• Lifetime: ~30 days (validated on startup)
• Format: JSON with cookies + timestamp

🐛 Troubleshooting

Server Won't Start

# Missing KAGI_TOKEN
export KAGI_TOKEN="your_token_here"

# Permission issues
chmod 600 ~/.kagi_mcp/cookies.json

# Clear stale cookies
rm ~/.kagi_mcp/cookies.json

Authentication Issues

# Re-authenticate manually
uv run python tests/auth_helper.py

# Verify token is valid
curl "https://kagi.com/search?token=your_token"

📈 Performance Benefits

• Startup Time: ~3x faster after first auth (no browser launch)
• Memory Usage: Lower (no persistent browser instances)
• Network: Reduced (cookie reuse vs repeated auth)
• UX: Instant tool availability for MCP clients

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run the test suite: uv run python tests/test_integration.py
5. Submit a Pull Request

📚 Documentation

• FastMCP Documentation: Learn about FastMCP
• README_FASTMCP.md: Detailed technical documentation
• Model Context Protocol: MCP specification

⚖️ License

Apache 2.0. See LICENSE.

🏆 Credits

FastMCP Implementation: Built with modern FastMCP 2.0 architecture
Original FastAPI Version: Based on yuchanns/kagiapi

---

Authenticate once, search for weeks. Built for the MCP ecosystem. 🚀