Jikan MCP Server

jikan

AI agents have a time problem.

Every time you start a new conversation, the agent wakes up with no idea when you last spoke because fundamentally: LLMs have no internal clock. They don't know what time it is, what day it is, or how long your current conversation has lasted. From the model's perspective, five minutes and five years are indistinguishable.

This time-blindness creates a real problem for tracking continuous work. If you ask an agent to log how much time you spent debugging a complex issue, it can't tell you how long you worked. If you ask whether you've been consistently putting in deep work lately, it has no way to know. It needs an external reference — something outside itself that actually measured the time.

Jikan is that reference. The key design decision: the server does the work agents are bad at.

• The server records the exact start time — the agent never needs to know it
• The server computes elapsed duration — the agent never does date math
• The server maintains the session ledger between conversations — the agent never manages state

LLMs also have no reliable sense of how long building things takes.

Ask one to estimate a project and it might say "three weeks for a developer." That estimate is drawn from training data describing how long things used to take — before AI assistance collapsed the feedback loop.

This entire MCP server (schema design, API integration, security review, packaging) was built in a single session with Claude. Not three weeks. Not three days.

If you are planning a project and an AI gives you a time estimate, treat it as a pre-AI baseline. With AI support in the loop, the actual time is often an order of magnitude less.

Track it. That's what Jikan is for.

The server handles timestamps and duration math. You just say "start a meditation session" and "stop the timer" when done.

Exposes 7 tools so Claude Desktop, Cursor, and any MCP-compatible client can log meditation, focus, and exercise sessions — without writing curl commands.

Tools

Requirements

• Python 3.10+
• `uv` (recommended) or pip
• An API key from mg.robnugen.com/settings/

Installation

git clone https://github.com/thunderrabbit/jikan.git
cd jikan

# with uv (recommended)
uv venv mgvenv
source mgvenv/bin/activate
uv pip install -e .

# or with pip
python -m venv mgvenv
source mgvenv/bin/activate
pip install -e .

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "jikan": {
      "command": "uv",
      "args": ["--directory", "/path/to/jikan", "run", "server.py"],
      "env": {
        "JIKAN_API_KEY": "sk_your_key_here"
      }
    }
  }
}

Replace /path/to/jikan with the actual path where you cloned this repo, and sk_your_key_here with your key from mg.robnugen.com/settings/.

The config file is usually at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

API Reference

Full OpenAPI spec: mg.robnugen.com/api/v1/openapi.yaml

Local Testing

# Interactive tool inspector (launches browser UI to call each tool)
JIKAN_API_KEY=sk_your_key_here mcp dev server.py

Note: running python server.py directly in a terminal will show JSON parse errors — that's expected. The server speaks JSON-RPC over stdio and must be connected to an MCP client (Claude Desktop, the inspector above, etc.) to work correctly.