caddyglow-kagi-mcp 0.1.0

MCP server wrapping kagi-cli.

caddyglow-kagi-mcp

MCP server that exposes Kagi services through the Python client shipped by 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:

KAGI_SESSION="your_session_value_from_link"

Install

uv sync

Run

export KAGI_SESSION="your_session_value_from_link"
uv run kagi-mcp

Or, with .env present:

uv run kagi-mcp

Run without a persistent project environment:

KAGI_SESSION="your_session_value_from_link" uvx caddyglow-kagi-mcp

Run from this checkout with uvx:

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

Check the installed version:

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:

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:

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:

http://127.0.0.1:8765/mcp

SSE is also supported:

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:

http://127.0.0.1:8765/sse

Equivalent CLI flags are available:

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:

[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:

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:

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

For SSE, use:

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

Claude Desktop Example

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

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:

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

Or add the equivalent JSON manually:

{
  "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

uv run pytest
uv run ruff check .