Dawarich

Disclaimer: This project is a work in progress and was vibe-coded without much of a plan. Treat it as experimental until the API surface and behavior have been reviewed more deliberately.

FastMCP server for Dawarich location history.

The server exposes LLM-friendly tools and resources for maps, stats, places, visits, points, and trip workflows. Dawarich currently does not expose /api/v1/trips, so trip mutation tools return a clear unsupported-capability response until those routes exist.

Configuration

Required:

• DAWARICH_BASE_URL: Dawarich base URL, for example http://dawarich.dawarich.svc.cluster.local:3000
• DAWARICH_API_KEY: Dawarich user API key

Optional:

• DAWARICH_AUTH_MODE: bearer or query, default bearer
• DAWARICH_HOST_HEADER: optional HTTP Host header for deployments that call an internal service URL while Dawarich only allows the public app host
• DAWARICH_FORWARDED_PROTO: optional X-Forwarded-Proto header, for example https when Dawarich forces HTTPS behind a proxy
• DAWARICH_TIMEOUT_SECONDS: default 30
• DAWARICH_MAX_PAGE_SIZE: default 500
• MCP_TRANSPORT: stdio or http, default stdio outside the container
• MCP_HOST: default 127.0.0.1
• MCP_PORT: default 8000

Local Development

uv --cache-dir /tmp/uv-cache-dawarich-mcp run --extra dev pytest
uv --cache-dir /tmp/uv-cache-dawarich-mcp run --extra dev ruff check .

Run over stdio:

DAWARICH_BASE_URL=https://timeline.example.test \
DAWARICH_API_KEY=... \
uv run dawarich-mcp --transport stdio

Run over HTTP:

DAWARICH_BASE_URL=https://timeline.example.test \
DAWARICH_API_KEY=... \
uv run dawarich-mcp --transport http --host 127.0.0.1 --port 8000

HTTP MCP endpoint: http://127.0.0.1:8000/mcp

Health endpoint: http://127.0.0.1:8000/health

Kubernetes Shape

The intended cluster deployment is internal only:

• Namespace: dawarich
• Service: dawarich-mcp
• URL: http://dawarich-mcp.dawarich.svc.cluster.local:8000/mcp
• No IngressRoute
• Dawarich API URL: http://dawarich.dawarich.svc.cluster.local:3000

Store the API key in a Kubernetes Secret. Do not commit it.

automated-setups expects the secret at:

namespace: dawarich
name: dawarich-mcp-secret
key: api-key

The image build and deployment can be run separately:

# Build the configured localhost/dawarich-mcp image into Spark's k8s.io containerd namespace.
direnv exec . env ANSIBLE_LOCAL_TEMP=/tmp/ansible-local TMPDIR=/tmp \
  venv/bin/ansible-playbook -i inventory/k8s_cluster/inventory.ini \
  playbooks/cluster/applications.yml --tags dawarich-mcp-build

# Apply the internal-only Deployment and ClusterIP Service.
direnv exec . env ANSIBLE_LOCAL_TEMP=/tmp/ansible-local TMPDIR=/tmp \
  venv/bin/ansible-playbook -i inventory/k8s_cluster/inventory.ini \
  playbooks/cluster/applications.yml --tags dawarich-mcp-deploy

The deploy tag refuses to apply the Deployment unless either dawarich_mcp_api_key is set from Ansible Vault or the dawarich-mcp-secret already exists in the dawarich namespace.

Safety

• Bearer auth is preferred so the Dawarich API key is not placed in URLs.
• Delete, merge, bulk update, and recalculation tools default to dry-run.
• Raw point reads are available but described as lower-level tools; prefer timeline, stats, and map context first.
• Trip tools intentionally do not scrape Dawarich HTML forms. They report the missing /api/v1/trips API instead.