oruk-mcp

Model Context Protocol server for oruk — live broadcast intelligence. Lets Claude Desktop, Cursor, Continue.dev, and any MCP-aware client search corroborated real-time news from radio, TV, and structured feeds, and integrate the oruk API into agentic workflows.

What it does

oruk-mcp exposes the oruk REST API to your LLM as MCP tools, resources, and prompts. Once configured, you can ask Claude or Cursor questions like:

• "What's breaking in the Middle East right now?"
• "Track tariff news from the past 12 hours and group by region."
• "Pull story evt_8f3a2b and show me every independent source that confirms it."
• "Walk me through how to integrate oruk's SSE stream into a Python service."

Install

Quickest — npx (no install)

npx -y oruk-mcp

Local install

npm install -g oruk-mcp
oruk-mcp

Both work without an API key against the public oruk wire. Set ORUK_API_KEY (free key at oruk.ai/dashboard) for the full filter surface, arbitrary story-id lookups, and lower-delay SSE.

Client configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "oruk": {
      "command": "npx",
      "args": ["-y", "oruk-mcp"],
      "env": {
        "ORUK_API_KEY": "ork_xxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. The oruk tools will appear in the tool picker.

Cursor

Open Settings → MCP and add:

{
  "oruk": {
    "command": "npx",
    "args": ["-y", "oruk-mcp"],
    "env": { "ORUK_API_KEY": "ork_xxxxxxxxxxxx" }
  }
}

Or edit ~/.cursor/mcp.json directly.

Continue.dev (VS Code)

In ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "oruk",
      "command": "npx",
      "args": ["-y", "oruk-mcp"],
      "env": { "ORUK_API_KEY": "ork_xxxxxxxxxxxx" }
    }
  ]
}

Other clients

Anything that speaks MCP over stdio will work. The binary is oruk-mcp and reads from stdin / writes to stdout. Logs go to stderr.

Discovery and transport

The official production transport today is stdio via npm:

npx -y oruk-mcp

Package metadata includes mcpName: "ai.oruk/oruk-mcp" and a server.json descriptor for MCP registries and agent directories. Oruk does not currently publish a production remote MCP endpoint. A remote Streamable HTTP endpoint is planned for a later beta after OAuth-style connector auth, per-key quotas, origin controls, and audit logs are in place.

Environment

| Variable | Default | Notes | | --- | --- | --- | | ORUK_API_KEY | unset | Optional. Lifts rate limits, unlocks /v1/stories filters and arbitrary story lookups. | | ORUK_API_BASE | https://api.oruk.ai | Override for staging or self-hosted. | | ORUK_MCP_DEBUG | 0 | Set to 1 for verbose stderr logging. |

Tools

| Tool | What it does | | --- | --- | | oruk_get_latest | Fetch the freshest stories with optional category, region, country, urgency, impact, since filters. | | oruk_search_news | Full-text search across recent stories. | | oruk_get_breaking | Convenience wrapper for high-urgency stories (urgency=breaking, impact ≥ 5). | | oruk_get_story | Full detail of a single story by evt_… id, including timeline and verbatim source quotes. | | oruk_get_topic | Stories in a single category, with the editorial description of what that category covers. | | oruk_list_categories | All 12 oruk categories with one-line descriptions. | | oruk_list_sources | Every monitored radio / TV / social / structured feed (requires ORUK_API_KEY). | | oruk_get_stats | Live system stats: active sources, story count, top categories (requires ORUK_API_KEY). | | oruk_get_corroboration | Independent sources and verbatim quotes for one story. | | oruk_describe_api | Full REST/SSE reference for users building integrations. | | oruk_show_pricing | Tier comparison (Free, Pro, Developer, Enterprise). | | oruk_health | Backend health (status, active streams, story count). |

Resources

The host can attach these oruk://… URIs to the model's context:

• oruk://docs/quickstart — 60-second setup guide
• oruk://docs/api-reference — concise REST + SSE reference
• oruk://docs/methodology — pipeline, sourcing, quality controls
• oruk://docs/categories — the 12-category taxonomy
• oruk://docs/pricing — tier table
• oruk://stories/latest — live snapshot of the freshest 25 stories

Prompts

User-controlled templates surfaced as slash-commands in MCP-aware clients:

• /summarize_breaking — short briefing of urgent stories, optional category/region filter
• /track_topic — chronological summary of a topic over the past N hours
• /morning_briefing — structured "what happened overnight" rundown grouped by category

Without an API key

The public /v1/stories/feed endpoint is open. When ORUK_API_KEY is unset, the server falls back to scanning the last ~100 stories on the feed and applies all filters client-side. This is good for almost every interactive query but trims:

• Stories older than the freshest ~100 events
• oruk_list_sources and oruk_get_stats (require auth)
• Arbitrary evt_… lookups beyond the recent window

The server emits a mode: "public" | "authed" field on structured output so the LLM knows which path was taken and can suggest the user provide a key when relevant.

Development

The source repository is private. Public users can install and run the published package directly; maintainers can run the same commands from their private checkout.

npm install
npm run build
node scripts/smoke.mjs           # full end-to-end protocol test against the live API
npm run inspect                  # launch @modelcontextprotocol/inspector against this server

Privacy & security

• The server is read-only; every tool is annotated readOnlyHint: true.
• Outbound requests go to https://api.oruk.ai over TLS (or ORUK_API_BASE).
• The API key is read from ORUK_API_KEY and never logged.
• Logs go to stderr only — stdout is reserved for MCP protocol traffic.
• The public no-key mode only scans the public feed. Authenticated tools use the same quotas as the REST API.

Changelog

1.1.2 - 2026-04-29

• Adds MCP registry-oriented metadata: mcpName: "ai.oruk/oruk-mcp" and a packaged server.json descriptor for stdio clients and agent directories.

1.1.1 - 2026-04-29

• Public package metadata and README now point to self-contained Oruk docs, npm, and support channels instead of the private source repository.

1.1.0 — 2026-04-28

• Bug fix: region and country filters now match. Previous versions filtered on s.region and s.country, but the API ships those values under s.eventRegion / s.eventCountry, so filters silently never matched.
• Bug fix: s.city can be either a string or ["array"]; rendering and filtering now handle both via the new storyCity() / storyRegion() / storyCountry() helpers.
• In-process cache with 3 s TTL on /v1/stories/feed (matches the backend's own Cache-Control: max-age=3). Multi-tool turns inside one MCP session collapse to a single backend hit — second and third calls return in ~0 ms.
• Public-feed fallback now passes an explicit since_hours=2 and caps the upstream fetch at 50 to avoid backend timeouts; params.limit still bounds the final returned slice.
• since parameter is now validated as ISO 8601 (2026-04-28 or 2026-04-28T15:00:00Z); free-form strings like yesterday are rejected.
• country parameter validated as ISO 3166-1 alpha-2 with a friendly Zod error.
• 429 handling now honors Retry-After and retries once when the wait is ≤ 8 s.
• API key never logged. New client.redactedKey() masks the key for the debug-mode boot log (ork_xxxx***xxxx).
• Tools now annotate structuredContent.mode: "public" | "authed" and structuredContent.meta.window_hours so the LLM (and you) know exactly what was scanned.

1.0.0 — 2026-04-28

• Initial release. 12 tools, 6 resources, 3 prompts, stdio transport.

License

MIT. See LICENSE.

Issues

Bugs, feature requests, and "I want a tool that..." -> [email protected]