Skip to main content
Glama
needle-mcp

needle-mcp

by srewoo

needle-mcp

A generic, credential-free MCP server that gives any Claude session (Claude Code, Claude Desktop, claude.ai) RCA-investigation building blocks — plus a ported, vendor-agnostic investigation methodology. It runs no LLM loop of its own and holds no Anthropic API key: the host Claude session you already have open does all the reasoning, using its own credentials for whatever vendor MCPs (Datadog, Splunk, GitLab, Sourcegraph, PagerDuty, ...) you already have connected.

What it is NOT

  • Not a Datadog/Splunk/GitLab client — it never talks to those vendors directly. If you have a vendor MCP connected, your host Claude uses that, with your own credentials for it.

  • Not a server-side agent — no orchestration loop, no Anthropic API key, no server cost.

  • Not stateful — no query history, no cache, no session store. Every tool call is independent.

Related MCP server: claude-code-mcp

Install

Published to npm, so no checkout is needed:

npx needle-mcp --help

Requires Node.js 18.17 or newer. There are no runtime credentials to configure — needle-mcp has none of its own.

claude mcp add needle-mcp -- npx -y needle-mcp

That registers the 7 tools. For the full experience, install it as a plugin instead — this additionally bundles the rca-methodology skill and a Stop hook that validates any RCA envelope your session claims to have produced, before the turn can end.

A plugin is installed from a marketplace, not from a bare path, so the repo ships its own one-entry marketplace manifest and you add that first:

git clone <this repo> ~/needle-mcp
cd ~/needle-mcp && npm install && npm run build   # required: the plugin runs dist/
claude plugin marketplace add ~/needle-mcp
claude plugin install needle-mcp@needle-mcp

Then restart Claude Code. MCP tool connections are established at session start, so a plugin installed mid-session is not picked up until the next one.

npm run build is not optional here: plugin.json launches dist/index.js and the Stop hook imports dist/tools/validateRca.js. Without it you get a server that will not start and a hook that fails open — enforcement silently off.

The plugin path needs a checkout because the hook and skill are files Claude Code loads from disk, not things the MCP protocol can deliver.

Claude Desktop / other MCP hosts

Add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "needle-mcp": {
      "command": "npx",
      "args": ["-y", "needle-mcp"],
      "env": { "NEEDLE_MCP_CONFIG_DIR": "/absolute/path/to/your/config/dir" }
    }
  }
}

No plugin mechanism exists on these hosts, so there's no Stop-hook enforcement — validate_rca is a tool your session can call (and the methodology is delivered via the server's MCP instructions/prompts), but following it is best-effort, not guaranteed. This is a known, accepted tradeoff, not parity with the Claude Code experience.

claude.ai

Run with the HTTP transport and register it as a remote MCP server:

npx needle-mcp --http 8000

Developing

npm install
npm test          # vitest, 207 tests
npm run typecheck # tsc --noEmit, strict
npm run build     # emits dist/

Configure your own sources (optional)

You almost certainly already have MCPs for your vendors — needle-mcp is designed to compose with those, not replace them. Only fill in adapters.yaml for a backend that genuinely has no MCP (an in-house log API, for example):

cp adapters.example.yaml adapters.yaml
cp topology.example.yaml topology.yaml
# edit both — adapters.yaml has 3 working reference configs (Loki, OpenSearch,
# Splunk-style) to copy from; topology.yaml already has vendor-generic
# coverage facts, add your own resource types as needed.

Both files are read from NEEDLE_MCP_CONFIG_DIR (falling back to CLAUDE_PROJECT_DIR, then the process cwd). Set it explicitly — an MCP server launched by a desktop host inherits an unpredictable working directory, so relying on cwd usually means your config is silently never found.

How you actually use it

Ask a question. The common case. You already have your vendor MCPs connected; needle-mcp supplies the method and the final check.

"Why is checkout 500ing in prod since 10am?"

Claude establishes the environment and window, queries your own Datadog/Splunk/ Loki tools, applies the five rules from the bundled methodology, and calls validate_rca on its own draft before answering.

Start from an identifier. A session id, request id, or trace id and nothing else.

"RCA for session sess_abc123XYZ"

Claude calls plan_investigation, which classifies the id, lists every vendor spelling it may appear under, names which sources can answer for it, and sets the right time window — then fans out across your connected tools.

Start from a screenshot. Paste it. Claude reads it directly (it is multimodal), pulls the failing URL/status/timestamp out of the image, and goes from there. There is no tool call needed for this and you should not make one.

Start from a HAR. Export the browser's Network tab, then:

"Run analyze_visual_evidence on ~/Downloads/checkout.har"

You get back only the failed and slow requests with their correlation headers, redacted — the fastest path from "the UI is broken" to a backend trace id.

5-minute first run (zero vendor MCPs required)

  1. Install needle-mcp as above — no other MCP needed for this walkthrough.

  2. Export your browser's Network tab as a HAR for the failing request.

  3. Ask Claude: "use analyze_visual_evidence on this HAR to find what failed."

  4. Feed the returned correlation headers/request id into correlate_ids if you have more log snippets to tie together.

  5. If you have an in-house log API, add it to adapters.yaml and ask Claude to query_generic_source it with the request id.

  6. Ask Claude to write the RCA — it calls validate_rca on its own draft and emits a fenced BEGIN_NEEDLE_MCP_RESULT_JSON envelope before finalizing.

Tools

Tool

Purpose

plan_investigation

Start here from a bare session/request/trace id: classifies it, gives every vendor spelling, names which sources can answer, sets the window

correlate_ids

Extract & rank correlation IDs across log snippets you've already collected, including async (message/job id) hops

analyze_visual_evidence

Parse a HAR/network-tab export (redacted). Not needed for screenshots — read those directly

query_generic_source

Config-templated REST query for a backend with no dedicated MCP — use only as a last resort

list_generic_sources

List what's declared in adapters.yaml

get_coverage

Look up whether a surface covers/is blind to a resource type, from topology.yaml

validate_rca

Deterministically lint a draft RCA envelope before you post it

Known limitations (v1)

  • query_generic_source supports static-header and HTTP-basic auth only — no OAuth client-credentials flows. Write a small dedicated MCP server for those instead.

  • analyze_visual_evidence's raw-image path can approach the ~1MB single-message size ceiling most MCP transports impose, on large screenshots.

  • validate_rca's investigation_log is self-reported by the host, not independently observed — a fabricated log cannot be caught here.

  • Enforcement is only non-optional on Claude Code (via the plugin's Stop hook). On Claude Desktop and claude.ai, validate_rca is a tool the session can decline to call.

  • Pinned to mcp>=1.9.0,<2: mcp 2.x renamed FastMCP to MCPServer. Porting is tracked as a follow-up.

Available Tools

7 tools
analyze_visual_evidenceA

Extract structured evidence from a HAR / browser network-tab export: failed and slow requests, with correlation headers, redacted.

If you already have a screenshot in your own context, reason about it directly — do NOT pass it here. The image_base64 parameter returns the image unchanged (this tool runs no vision model), so round-tripping one you can already see just puts a second copy in your context. Pass it only if you need the image echoed back alongside HAR findings.

Inputs: context, har_json, har_path, image_base64, +1 more.

correlate_idsB

Extract and rank correlation IDs (request/trace/span/message/job) shared across log snippets you've already collected elsewhere. Use this to carry an identifier forward across a sync-to-async hop (e.g. an HTTP request into a Kafka consumer).

Inputs: evidence_snippets (required).

get_coverageA

Look up which observability surfaces cover (or are blind to) a resource type, from topology.yaml. If unknown_coverage is true, you may NOT conclude absence from an empty query result for this resource type.

Inputs: resource_type (required).

list_generic_sourcesB

List the sources declared in adapters.yaml for this deployment.

Inputs: no named parameters. Returns: result

plan_investigationA

START HERE when the user hands you a bare identifier — a session id, request id, trace id, or correlation id — with no logs yet. Classifies the identifier's shape, returns every vendor spelling it may appear under, names which configured sources and coverage surfaces can answer for it, and suggests a time window (widened when the id looks async). Use correlate_ids instead once you already have log snippets in hand.

Inputs: identifier (required), environment.

query_generic_sourceA

Query a source declared in adapters.yaml via a config-templated REST call. Use ONLY when no vendor MCP (Datadog/Splunk/Loki/etc.) already covers this source — prefer your own connected MCPs first.

Inputs: end (required), start (required), params (required), source (required), +1 more.

validate_rcaA

Deterministically lint a draft RCA's structured claim before you post it. Call this before finalizing any RCA, and emit the envelope fenced between BEGIN_NEEDLE_MCP_RESULT_JSON and END_NEEDLE_MCP_RESULT_JSON — on Claude Code a Stop hook re-runs this check against that block regardless.

Inputs: claim_json (required), investigation_log.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct stage of the investigation workflow: plan_investigation starts from a bare identifier, correlate_ids handles already-collected snippets, generic source query/list handle adapter access, get_coverage handles topology, analyze_visual_evidence handles HAR, and validate_rca handles output. The only near pair is explicitly disambiguated in the descriptions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (plan_investigation, query_generic_source, list_generic_sources, validate_rca). There is no style mixing or vague verb usage.

    Tool Count5/5

    Seven tools is a well-scoped set for an observability/RCA investigation server. Each tool maps to a distinct workflow step without redundancy or bloat.

    Completeness5/5

    The tool surface covers the full investigation lifecycle: identifying a trace ID, querying sources, listing sources, checking coverage, correlating IDs across snippets, analyzing HAR evidence, and validating the final RCA. Vendor-specific log retrieval is intentionally deferred to connected MCPs, so there is no obvious dead-end in the intended workflow.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI-driven incident response by connecting Claude to monitoring tools like Prometheus, Grafana, Loki, PagerDuty, and Slack for automated investigation and runbook generation.
      9
      -
    • A
      license
      A
      quality
      D
      maintenance
      Wraps Claude Code as tools for MCP clients, enabling autonomous coding tasks via a 4-tool lifecycle with session management, async polling, and permission controls.
      4
      93 npm
      21
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables search, analytics, and visualization of Claude Code sessions with MCP tools for session management, recovery, and insights.
      10
      147 PyPI
      1
      MIT