io-mcp

Local Research & Homelab Assistant Toolkit — a Python tool suite that automates research workflows (paper discovery, relevance scoring, digests) and homelab monitoring (Prometheus, logs), exposed through an MCP server for Open WebUI and a CLI for cron/systemd jobs. Both frontends share one core library. LLM inference is local via Ollama — no cloud API dependencies.

Features

• Paper digests — query arXiv + Semantic Scholar for your interests, score relevance with a local model, and push a digest to ntfy.

• Homelab status — structured host health and raw PromQL against Prometheus.

• Log summaries — journald logs summarized by a local model.

• Two frontends, one core — MCP (Streamable HTTP) for Open WebUI, CLI for cron.

Related MCP server: openresearch-mcp

Install

Target is Fedora / any systemd Linux. One script sets up an isolated environment (venv or conda), installs io-mcp, and (optionally) systemd units:

git clone <your-remote> io-mcp && cd io-mcp
./deploy/install.sh --systemd --timer            # venv
# or: ./deploy/install.sh --method conda --systemd --timer

Full deployment details, options, and external-service setup: deploy/README.md.

Manual install (development)

python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'      # editable is required (prompts/ resolves at runtime)
io-mcp init                  # writes ~/.config/io-mcp/config.yaml + state.db

Configuration

Single YAML file at ~/.config/io-mcp/config.yaml (see config.example.yaml). Any value can be overridden by an environment variable with the IO_MCP_ prefix and __ nesting:

IO_MCP_OLLAMA__BASE_URL=http://localhost:11434
IO_MCP_NTFY__BASE_URL=http://10.0.0.88
IO_MCP_SERVER__PORT=8484

io-mcp config prints the fully resolved configuration.

Semantic Scholar API key (optional)

Paper discovery uses arXiv + Semantic Scholar. The unauthenticated Semantic Scholar API is a shared, heavily throttled pool (HTTP 429); discovery retries with backoff and, if it stays throttled, degrades gracefully to arXiv alone. For reliable Semantic Scholar results, get a free API key and expose it in the environment where the digest runs (it is never stored in config):

export SEMANTIC_SCHOLAR_API_KEY=your-key-here

For the systemd timer, uncomment the Environment= line in deploy/io-mcp-digest.service.

CLI

io-mcp digest              Run discovery → score → digest → notify (ntfy)
  --dry-run                Show results without notifying
  --since YYYY-MM-DD       Override lookback date
  --interests NAME         Restrict to specific interest group(s)
  --prune-days N           Prune seen papers older than N days after the run
io-mcp search QUERY        One-off paper search (--source arxiv|s2|both, --limit N, --score)
io-mcp homelab-digest      Snapshot homelab health; alert via ntfy on problems
  --dry-run                Show results without notifying
  --always                 Notify even when everything is healthy
  --summarize              Add an Ollama natural-language summary (uses the GPU)
io-mcp status              Homelab host health (--host NAME, --json)
io-mcp query PROMQL        Raw PromQL query
io-mcp logs                Summarize logs (--host, --unit, --since, --priority)
io-mcp serve               Start the MCP server (--host, --port)
io-mcp config              Print resolved configuration
io-mcp init                Create default config + state database

MCP server

io-mcp serve      # binds server.host:server.port from config, path /mcp

Connect in Open WebUI: Admin Settings → External Tools → + Add Server → MCP (Streamable HTTP) → http://127.0.0.1:8484/mcp. Exposed tools: search_papers, score_paper, run_digest, recent_papers, host_status, service_status, probe_status, homelab_overview, query_prometheus, send_notification, summarize_logs, list_tools.

list_tools is a self-describing helper: some clients (e.g. Open WebUI) collapse the whole server into a single io-mcp entry, so the agent can call list_tools to discover the individual tools with their descriptions and parameters.

Development

pip install -e '.[dev]'
pytest          # all external services are mocked; no network needed
ruff check .

Project layout

io_mcp/            core library (config, state, ollama, notify) + tools/ + server + cli
prompts/           system prompts (loaded at runtime; keep with the repo)
deploy/            install.sh, systemd units, crontab example, deployment guide
tests/             pytest suite (mocked APIs, in-memory SQLite)

Requirements

• Python ≥ 3.11

• Ollama with your chosen models pulled

• ntfy (self-hosted or ntfy.sh) for digest notifications

• Prometheus + node_exporter for homelab tools (optional)