osqueryi-mcp
Simple Local STDIO MCP Server
Install / Use
claude mcp add mdfranz -- npx -y github:mdfranz/osqueryi-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
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.
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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| osqueryi-mcp (this skill)by mdfranz | 71 | 3 | 35d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.7k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.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.
Skill content
View source on GitHubosqueryi-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
osqueryibinary. 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 throughosqueryi, 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_queryintentionally passes its SQL through toosqueryi; it is not restricted to a SELECT-only subset. Every invocation uses--config_path=/dev/nullto 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_queryfailures 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 ondescribe_table. - Observability: Structured logging (via
slog) goes toosqueryi-mcp.logby default. A PID lock prevents another server using the same configured lock file from starting.
Prerequisites
- osquery: You must have
osqueryinstalled on your system. Makeosqueryiavailable onPATH, or setOSQUERYI_PATHto its full path. - Go: Version 1.26.5 or later (required to build from source).
Installation
From Source
-
Clone the repository:
git clone https://github.com/mdfranz/osqueryi-mcp.git cd osqueryi-mcp -
Build the binary:
make buildThis will create an
osqueryi-mcpbinary in the project root. -
(Optional) Install to
~/.local/bin(create the directory first if needed, and ensure it is onPATH):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_tableorpreview_tableare saved to the cache. - Manual Refresh: Use the
refresh_cachetool to force a full reload of all table schemas fromosqueryi. - Disabling: Set
OSQUERYI_CACHEFILE=offto 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 usinggo 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-mcpevolved 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
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
