Metadata-Version: 2.4
Name: caddyglow-kagi-mcp
Version: 0.1.0
Summary: MCP server wrapping kagi-cli.
License-Expression: MIT
Requires-Dist: kagi-cli>=0.1.0
Requires-Dist: mcp>=1.21.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# caddyglow-kagi-mcp

MCP server that exposes Kagi services through the Python client shipped by
[`kagi-cli`](https://pypi.org/project/kagi-cli/).

## Requirements

- Python 3.12+
- `uv`
- A valid `KAGI_SESSION` value from your Kagi session link

You can provide `KAGI_SESSION` through the environment or through a project-local `.env` file:

```dotenv
KAGI_SESSION="your_session_value_from_link"
```

## Install

```bash
uv sync
```

## Run

```bash
export KAGI_SESSION="your_session_value_from_link"
uv run kagi-mcp
```

Or, with `.env` present:

```bash
uv run kagi-mcp
```

Run without a persistent project environment:

```bash
KAGI_SESSION="your_session_value_from_link" uvx caddyglow-kagi-mcp
```

Run from this checkout with `uvx`:

```bash
KAGI_SESSION="your_session_value_from_link" uvx --from /home/rick/projects-caddy/kagi-mcp kagi-mcp
```

Check the installed version:

```bash
uvx caddyglow-kagi-mcp --version
```

The server communicates over stdio for MCP clients.

Logging is written to stderr so it does not corrupt MCP stdio messages. The default log level is
`WARNING`; set `KAGI_MCP_LOG_LEVEL` to `INFO` or `DEBUG` when troubleshooting:

```bash
KAGI_MCP_LOG_LEVEL=INFO uv run kagi-mcp
```

## HTTP and SSE Transports

Stdio is the default transport. For HTTP clients, run the server with either streamable HTTP or SSE:

```bash
KAGI_SESSION="your_session_value_from_link" \
KAGI_MCP_TRANSPORT=streamable-http \
KAGI_MCP_HOST=127.0.0.1 \
KAGI_MCP_PORT=8765 \
uvx caddyglow-kagi-mcp
```

The streamable HTTP endpoint is:

```text
http://127.0.0.1:8765/mcp
```

SSE is also supported:

```bash
KAGI_SESSION="your_session_value_from_link" \
KAGI_MCP_TRANSPORT=sse \
KAGI_MCP_HOST=127.0.0.1 \
KAGI_MCP_PORT=8765 \
uvx caddyglow-kagi-mcp
```

The SSE endpoint is:

```text
http://127.0.0.1:8765/sse
```

Equivalent CLI flags are available:

```bash
uvx caddyglow-kagi-mcp --transport streamable-http --host 127.0.0.1 --port 8765
```

## MCP Tools

- `kagi_search(query, fetch_all=False)`
- `kagi_ask(text, model="gpt-5-mini", thread=None, internet=True)`
- `kagi_summarize(url, summary_type="takeaway")`
- `kagi_proofread(text, lang="auto", style="general", level="standard", formality="default", context=None, model="standard")`

Each tool calls the `kagi_client` library directly and returns MCP-friendly dictionaries.

## Codex Example

For stdio, add this to `~/.codex/config.toml`:

```toml
[mcp_servers.kagi]
command = "uvx"
args = ["caddyglow-kagi-mcp"]

[mcp_servers.kagi.env]
KAGI_SESSION = "your_session_value_from_link"
KAGI_MCP_LOG_LEVEL = "WARNING"
```

For streamable HTTP, start the server separately:

```bash
KAGI_SESSION="your_session_value_from_link" \
KAGI_MCP_TRANSPORT=streamable-http \
KAGI_MCP_PORT=8765 \
uvx caddyglow-kagi-mcp
```

Then add this to `~/.codex/config.toml`:

```toml
[mcp_servers.kagi]
url = "http://127.0.0.1:8765/mcp"
```

For SSE, use:

```toml
[mcp_servers.kagi]
url = "http://127.0.0.1:8765/sse"
```

## Claude Desktop Example

From this checkout, add the server with the Claude CLI:

```bash
claude mcp add kagi \
  --env KAGI_SESSION="your_session_value_from_link" \
  -- uv --directory /home/rick/projects-caddy/kagi-mcp run kagi-mcp
```

Using `uvx` instead:

```bash
claude mcp add kagi \
  --env KAGI_SESSION="your_session_value_from_link" \
  -- uvx caddyglow-kagi-mcp
```

Or add the equivalent JSON manually:

```json
{
  "mcpServers": {
    "kagi": {
      "command": "uv",
      "args": ["--directory", "/home/rick/projects-caddy/kagi-mcp", "run", "kagi-mcp"],
      "env": {
        "KAGI_SESSION": "your_session_value_from_link",
        "KAGI_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}
```

## Development

```bash
uv run pytest
uv run ruff check .
```
