# Kagi MCP (Node.js)

A Node.js implementation of the Kagi Model Context Protocol (MCP) server. This provides a more stable alternative to the official Python implementation, especially when running multiple instances.

## Features

- Search web content using Kagi Search API
- Summarize documents, videos, and audio using Kagi Summarizer API
- No port conflicts when running multiple instances
- Full compatibility with Claude Desktop

## Prerequisites

- Node.js 18 or higher
- Kagi API key (request from support@kagi.com)
- **Note**: The Search API is in closed beta. You may need to request access separately.

## Installation

### Method 1: Using npx (Recommended for Claude Desktop)

No installation needed! Claude Desktop can run the package directly using npx.

### Method 2: Install from npm

```bash
npm install -g kagi-mcp
```

Or use it directly with npx:

```bash
npx kagi-mcp
```

### Method 3: Install from GitHub directly

```bash
npm install -g github:yuki-yano/kagi-mcp
```

### Method 4: Install from source

```bash
git clone https://github.com/yuki-yano/kagi-mcp.git
cd kagi-mcp
npm install
npm run build
npm link
```

## Configuration

### Environment Variables

- `KAGI_API_KEY` (required): Your Kagi API key
- `KAGI_SUMMARIZER_ENGINE` (optional): Summarization engine - cecil (default), agnes, daphne, or muriel

### Claude Desktop Configuration

Add the following to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Method 1: Using npx (Recommended - No installation required)

```json
{
  "mcpServers": {
    "kagi": {
      "command": "npx",
      "args": ["kagi-mcp"],
      "env": {
        "KAGI_API_KEY": "your-kagi-api-key"
      }
    }
  }
}
```

This method automatically downloads and runs the latest version from npm without requiring manual installation.

#### Method 2: Using globally installed package

```json
{
  "mcpServers": {
    "kagi": {
      "command": "kagi-mcp",
      "env": {
        "KAGI_API_KEY": "your-kagi-api-key"
      }
    }
  }
}
```

### Claude Code Configuration

To use with Claude Code CLI, run the following command:

```bash
claude mcp add kagi -s user -e KAGI_API_KEY="your-kagi-api-key" -- npx kagi-mcp
```

This will:
- Add the Kagi MCP server to your Claude Code configuration
- Set it up at the user level (`-s user`)
- Configure your API key as an environment variable
- Use npx to automatically download and run the latest version from npm

You can also use the MCP inspector for debugging:

```bash
# Method 1: Using npx (requires npm package to be published)
KAGI_API_KEY="your-kagi-api-key" npx @modelcontextprotocol/inspector npx kagi-mcp

# Method 2: Using local installation (more reliable)
npm install -g kagi-mcp
KAGI_API_KEY="your-kagi-api-key" npx @modelcontextprotocol/inspector kagi-mcp

# Method 3: Using source build
KAGI_API_KEY="your-kagi-api-key" npx @modelcontextprotocol/inspector node dist/index.js
```

## Usage

The MCP server provides two tools:

### kagi_search_fetch

Search the web using Kagi Search API.

```typescript
{
  "queries": ["array of search queries"]
}
```

### kagi_summarizer

Summarize content from a URL.

```typescript
{
  "url": "https://example.com/article",
  "summary_type": "summary" | "takeaway",  // optional
  "target_language": "EN"  // optional
}
```

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run built version
npm start
```

## Troubleshooting

### "Malformed authorization token" error

This error indicates that your API key is invalid or not properly formatted. Make sure:
- You have a valid Kagi API key from support@kagi.com
- The key is correctly set in your environment variable
- You're not adding extra quotes or spaces around the key

### "401 Unauthorized" error for Search API

The Search API is in closed beta. You may need to:
1. Request access to the Search API separately from support@kagi.com
2. Ensure your API key has the necessary permissions

### Testing your API key

You can test your API key using the included test script:

```bash
KAGI_API_KEY="your-api-key" node test-api.js
```

## License

MIT