SkillAgentSearch skills...

osqueryi-mcp

Simple Local STDIO MCP Server

Install / Use

claude mcp add mdfranz -- npx -y github:mdfranz/osqueryi-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

71/100

Supported Platforms

Claude Code
Claude Desktop

Tags

Our assessment of osqueryi-mcp

osqueryi-mcp scores 71/100 on our quality scale, 3865th of 4,706 Development & Engineering skills we index.

Its MCP Server is 12 KB long, well organised into 20 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.

It has 3 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
4/15
Adoption
3/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 35 days ago, so osqueryi-mcp is actively maintained.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 75/100, with 3 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

osqueryi-mcp compared with similar skills

All 4 of these similar skills score higher than osqueryi-mcp; compare them before choosing.

SkillScoreStarsUpdatedFormat
osqueryi-mcp (this skill)by mdfranz71335d agoMCP Server
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
Agent-Reachby Panniantong100112.7k10d agoCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
headroomby headroomlabs-ai10079.9ktodayCLAUDE.md

Frequently asked questions

How do I install osqueryi-mcp?
Run claude mcp add mdfranz -- npx -y github:mdfranz/osqueryi-mcp. The install tabs above show the steps for each supported agent.
Which AI agents does osqueryi-mcp work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is osqueryi-mcp safe to use?
It declares no license and scores 75/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is osqueryi-mcp still maintained?
The repository was last updated 35 days ago, so osqueryi-mcp is actively maintained.

osqueryi-mcp

osqueryi-mcp is a Model Context Protocol (MCP) server written in Go that exposes the local system's osquery tables as queryable tools. The MCP server communicates with its client over stdio; when an operation needs uncached osquery data, it starts osqueryi as a subprocess and reads its JSON output. This lets MCP clients inspect and query local system state using SQL.

Features

  • Runtime Discovery: Discovers the tables and schemas exposed by the installed osqueryi binary. Persisted cache data is reused until it is refreshed or removed.
  • Progressive Disclosure: Three primary tools support table exploration:
    • list_tables: List all available osquery tables on the current system.
    • describe_table: Get the schema (columns and types) for a specific table.
    • run_query: Execute SQL through osqueryi, including joins, and receive a JSON response subject to the server's output limits.
  • Workflow Helpers: Additional tools reduce common multi-step loops:
    • search_tables: Find relevant tables by table or column name.
    • preview_table: Return schema plus sample rows in one call.
    • query_table: Build a single-table query with validated table, column, ordering, and limit arguments.
    • refresh_cache: Clear and reload the cached list of tables and their schemas.
  • Guardrails: Structured tools validate table names and known columns. run_query intentionally passes its SQL through to osqueryi; it is not restricted to a SELECT-only subset. Every invocation uses --config_path=/dev/null to ignore the normal osquery configuration file on Unix-like systems.
  • Self-correcting errors: A rejected column names the table's valid columns, and an unknown table suggests near-miss names. run_query failures are annotated the same way, with the schema of each table the SQL referenced. This lets a caller fix a query from the error alone instead of spending another round trip on describe_table.
  • Observability: Structured logging (via slog) goes to osqueryi-mcp.log by default. A PID lock prevents another server using the same configured lock file from starting.

Prerequisites

  • osquery: You must have osquery installed on your system. Make osqueryi available on PATH, or set OSQUERYI_PATH to its full path.
  • Go: Version 1.26.5 or later (required to build from source).

Installation

From Source

  1. Clone the repository:

    git clone https://github.com/mdfranz/osqueryi-mcp.git
    cd osqueryi-mcp
    
  2. Build the binary:

    make build
    

    This will create an osqueryi-mcp binary in the project root.

  3. (Optional) Install to ~/.local/bin (create the directory first if needed, and ensure it is on PATH):

    mkdir -p ~/.local/bin
    make install
    

Configuration

The server is configured via environment variables:

| Variable | Default | Description | |---|---|---| | OSQUERYI_PATH | osqueryi | Path to the osqueryi binary. | | OSQUERYI_TIMEOUT | 30s | Maximum duration for a query to run. | | OSQUERYI_LOCKFILE | osqueryi-mcp.lock | Path to the PID lock file. Set to off to disable. | | OSQUERYI_CACHEFILE | osqueryi-mcp-cache.json | Path to the schema cache file. Set to off to disable. | | OSQUERYI_DEBUG | (unset) | Set to any value to enable debug-level logging. | | OSQUERYI_LOGFILE | osqueryi-mcp.log | Path to a file for logging. Set to off or use an empty string to log to stderr. | | OTEL_EXPORTER_OTLP_ENDPOINT | (unset) | Enables OpenTelemetry export when set together with OTEL_EXPORTER_OTLP_HEADERS. Use https://logfire-us.pydantic.dev for Logfire US or https://logfire-eu.pydantic.dev for EU. | | OTEL_EXPORTER_OTLP_HEADERS | (unset) | OTLP request headers. For Logfire: Authorization=<write token>. Keep the token out of source control. | | OTEL_SERVICE_NAME | osqueryi-mcp | Optional service name shown in Logfire. |

Logfire observability

Logfire export is disabled by default. To enable it, create a Logfire project and write token, then configure standard OpenTelemetry variables in the MCP client environment:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://logfire-us.pydantic.dev
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=your-write-token'
export OTEL_SERVICE_NAME=osqueryi-mcp

The server exports tool, osqueryi subprocess, and cache spans; aggregate latency/count/response-size metrics; and sanitized structured logs. Exported records carry the tool name, the queried table name, outcome, error category, duration, and payload sizes. They do not carry SQL, WHERE filters, ordering, result data, cache paths, or raw osquery error text — those stay in the local slog output. If telemetry cannot be initialized or exported, the MCP continues serving requests and logs a local warning instead.

OTEL_METRIC_EXPORT_INTERVAL (milliseconds) is worth setting for short-lived sessions: the SDK's 60-second default can elapse after the process has already exited, losing every metric for the run.

When a client propagates W3C trace context in the MCP request's _meta field — as logfire.instrument_mcp() does by default — the server continues that trace instead of starting its own, so tool spans nest under the calling agent's span. Clients that send no trace context are unaffected, and their server spans are simply roots.

Caching

osqueryi-mcp uses a local JSON file to cache osquery table names and their schemas. This reduces repeated schema lookups for tools such as search_tables, preview_table, and query_table.

  • On-Disk Persistence: The cache is saved to disk so it persists across server restarts.
  • Background Warming: On startup, the server attempts to fetch any missing schemas in a background task.
  • Auto-Update: Schemas fetched by describe_table or preview_table are saved to the cache.
  • Manual Refresh: Use the refresh_cache tool to force a full reload of all table schemas from osqueryi.
  • Disabling: Set OSQUERYI_CACHEFILE=off to disable persistent caching entirely.

The cache does not record the osqueryi version or check schema freshness. Run refresh_cache after upgrading or reconfiguring osquery, or remove the cache file to force rediscovery on the next start.

Result Limits

run_query, query_table, and preview_table limit returned data to keep MCP responses manageable. Results are truncated when they exceed the row or payload limits; the response includes a truncated indicator when truncation occurs. run_query and query_table return at most 100 rows after response processing, while preview_table accepts at most 100 rows. A requested query_table limit is capped at 1,000 rows before response processing. The server attempts to keep JSON payloads below approximately 16 KiB; a single oversized row can still exceed that target.

Usage with MCP Clients

To use an installed osqueryi-mcp binary with an MCP client (like Claude Desktop), add it to your configuration file. If you built from source without installing it, use the absolute path to the binary instead.

MCP Configuration

{
  "mcpServers": {
    "osqueryi-mcp": {
      "command": "/absolute/path/to/osqueryi-mcp"
    }
  }
}

An MCP server does not necessarily inherit the shell environment, so pass any settings it needs explicitly. Clients that support ${VAR} expansion can forward them without writing a token into the file; see .mcp.json in this repository:

{
  "mcpServers": {
    "osqueryi-mcp": {
      "command": "/absolute/path/to/osqueryi-mcp",
      "env": {
        "OTEL_EXPORTER_OTLP_ENDPOINT": "${OTEL_EXPORTER_OTLP_ENDPOINT:-https://logfire-us.pydantic.dev}",
        "OTEL_EXPORTER_OTLP_HEADERS": "${OTEL_EXPORTER_OTLP_HEADERS:-}"
      }
    }
  }
}

Because the server enables export only when both variables are non-empty, that configuration stays inert until a token is present in the environment. Servers receive their environment when they start, so restart the client after changing it.

Development

Makefile Targets

  • make build: Compiles the binary.
  • make run: Runs the server directly using go run.
  • make test: Runs the Go test suite (go test ./...).
  • make fmt: Formats the source code.
  • make vet: Runs Go static analysis.
  • make clean: Removes the compiled binary plus the default lock, cache, and log files.

Testing

The repository provides a direct MCP smoke harness and live LLM integration/benchmark harnesses. They require a working osqueryi installation and Python dependencies run through uv. The smoke harness resolves a built osqueryi-mcp binary from the project root; the framework harnesses require osqueryi-mcp on PATH.

These scripts exercise the local machine's live osquery data. The LLM harnesses also make billable provider API calls, so they are exploratory integration checks rather than deterministic regression tests.

Basic Smoke Test

uv run tools/test_mcp.py

This starts the local server over stdio, verifies initialization and the tool catalog, and invokes every MCP tool. It fails on protocol errors, unexpected tool failures, or a missing expected error for an invalid raw-SQL query.

The convenience runner builds the binary, runs this smoke harness, then runs the Agno, Strands, and Pydantic AI harnesses for every non-comment model in models.txt:

./run_tests.sh

If OTEL_EXPORTER_OTLP_ENDPOINT is unset and .logfire/logfire_credentials.json exists, the runner derives the OTLP endpoint and write token from that file so the Go server's telemetry lands in the same project as the harnesses' own. It reports which endpoint and service name it chose, or says telemetry is disabled. Exporting OTEL_EXPORTER_OTLP_ENDPOINT yourself takes precedence.

Framework-Specific Examples

These examples demonstrate how to connect LLM agents to osqueryi-mcp using popular Python frameworks:

  • Agno (Phidata): uv run tools/agno_test_mcp.py [model_id] — default: gemini-3.1-flash-lite-preview
  • Strands (AWS): uv run tools/strands_test_mcp.py [model_id] — default: claude-haiku-4-5
  • Pydantic AI: uv run tools/pydantic_ai_test_mcp.py [model_id] — default: claude-haiku-4-5

The LLM workloads and system prompts live in tools/prompts/osquery_benchmark.toml. Add a [[tasks]] entry there to run a new shared workload in all three frameworks. Keep the common prompt fields unchanged across frameworks for an apples-to-apples comparison.

Set the API key for the selected provider: OPENAI_API_KEY for OpenAI, GOOGLE_API_KEY (or GEMINI_API_KEY where supported) for Gemini, or ANTHROPIC_API_KEY for Claude. The harnesses default the MCP PID lock and server logfile to off so they can start their own temporary stdio server; explicitly supplied environment values take precedence.

When telemetry is enabled, Logfire receives the current 12-character Git revision as service.version for both the server and framework harnesses. Set OSQUERYI_GIT_REVISION when running a harness outside a Git checkout.

For a framework example after building in the project root without installing:

PATH="$PWD:$PATH" uv run tools/agno_test_mcp.py

To run the smoke harness with debug logging written to a file:

OSQUERYI_DEBUG=1 OSQUERYI_LOGFILE=osqueryi-mcp.log uv run tools/test_mcp.py
tail -f osqueryi-mcp.log

Documentation & Guides

Project & Optimization

  • Development Journey: The narrative of how osqueryi-mcp evolved from its MVP through subsequent implementation and tuning work.
  • Optimization Results: Detailed benchmarks and key findings on token efficiency, model comparisons (Gemini vs OpenAI), and system prompting.

Technical References

  • [Dependencies & Packa

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars3
CategoryDevelopment
Updated1mo ago
Forks0

Languages

Go

Trust signals

75/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium2 low