loggly-mcp
Read-only Loggly MCP server for querying logs, aggregating traffic, and enriching IPs with threat/ownership context.
Validate Loggly credentials and run low-level Loggly API searches, event retrieval, pagination, counts, volume metrics, stats, field listing/facets, and raw GET calls.
Get aggregation-first summaries: totals, top hosts/paths/status codes/user agents, timelines, and representative samples.
Scope traffic summaries by IP, host, or path; get facet counts by IP, path, or user agent; build bucketed timelines; sample events.
Perform IP intelligence: RDAP ownership, GreyNoise/AbuseIPDB reputation, and combined Loggly traffic context with cross-account correlation.
Target multiple configured Loggly accounts per tool call and operate read-only, blocking write endpoints.
Loggly MCP
Read-only Model Context Protocol (MCP) server for Loggly /apiv2/* APIs, plus IP
intelligence (RDAP, GreyNoise, AbuseIPDB). Exposes Loggly search/analytics/field tools,
aggregation-first traffic tools, and IP-context tools, while blocking write endpoints.
Skill Usage
For efficient log retrieval (less token use) and summarization, pair this server with a skill.
Quickstart
Install from npm
LOGGLY_SUBDOMAIN=your-subdomain LOGGLY_TOKEN=your-token npx -y @andrewbabu/loggly-mcpMCP client configuration:
{
"mcpServers": {
"loggly": {
"command": "npx",
"args": ["-y", "@andrewbabu/loggly-mcp"],
"env": {
"LOGGLY_SUBDOMAIN": "your-subdomain",
"LOGGLY_TOKEN": "your-token"
}
}
}
}Related MCP server: mcp-server-malcolm
Run from source
git clone https://github.com/andrewbabu/loggly-mcp.git
cd loggly-mcp
npm install
cp .env.example .envEdit .env with your Loggly credentials, then run:
npm startOnce the repo is trusted in Codex, the MCP server can also be started automatically via .codex/config.toml.
Configuration
The server loads .env from its working directory on startup.
Required
LOGGLY_SUBDOMAIN
Loggly account subdomain or full Loggly URL (e.g.your-subdomainorhttps://your-subdomain.loggly.com)LOGGLY_TOKEN
Loggly API token
Optional
LOGGLY_AUTH_MODEbearer(default) orbasicLOGGLY_MAX_RETRIES
Default:2LOGGLY_REQUEST_TIMEOUT_MS
Default:15000LOGGLY_LOG_LEVELerror,warn,info(default), ordebug
Remote (HTTP) Server
For a stdio server anyone on the team can reach from Claude Code without a local checkout, run the HTTP variant instead and host it on an internal server/VM.
cp .env.example .envEdit .env with your Loggly credentials plus MCP_BEARER_TOKEN (generate one with
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"), then:
npm run start:httpThis starts a stateless Streamable HTTP MCP server on MCP_HTTP_PORT (default 8787):
GET /healthz— unauthenticated liveness check.POST /mcp— the MCP endpoint. RequiresAuthorization: Bearer <MCP_BEARER_TOKEN>; every other request to/mcpgets401.
The Loggly credentials stay server-side — everyone connecting shares the same Loggly account
access. MCP_BEARER_TOKEN only gates access to the MCP server itself, so treat it as a secret
and rotate it if it leaks (e.g. re-generate and redistribute).
Only run this behind your internal network/VPN, not exposed directly to the public internet — there's a single shared token, not per-user auth.
Connecting from Claude Code
Each org member adds the remote server once:
claude mcp add --transport http loggly https://your-internal-host:8787/mcp \
--header "Authorization: Bearer <MCP_BEARER_TOKEN>"Swap in the internal hostname/port you deployed to and the token you were given.
Running with Docker
docker build -t loggly-mcp .
docker run -d --name loggly-mcp -p 8787:8787 --env-file .env loggly-mcpMultiple Accounts / Domains
The server can hold credentials for several Loggly accounts (different subdomains, different tokens) at once and target them per tool call.
Set LOGGLY_ACCOUNTS to a JSON object mapping an account name to its credentials:
LOGGLY_ACCOUNTS={"acme":{"subdomain":"acme","token":"acme_token","authMode":"bearer"},"beta":{"subdomain":"beta","token":"beta_token"}}When LOGGLY_ACCOUNTS is set, it replaces LOGGLY_SUBDOMAIN/LOGGLY_TOKEN/LOGGLY_AUTH_MODE.
Every tool then accepts an optional account argument (e.g. account: "acme") to pick which
account's credentials to use for that call.
If
accountis omitted, the server usesLOGGLY_DEFAULT_ACCOUNTif set, otherwise"default", otherwise the single configured account if there's only one.An unknown
accountvalue returns an error listing the configured account names.iterate_events_nextcan also infer the account from thenext_urlhost whenaccountis omitted, as long as exactly one configured account matches that host.
Existing single-account setups (just LOGGLY_SUBDOMAIN/LOGGLY_TOKEN) keep working unchanged —
they're treated as one account named "default".
Aggregation-First Traffic Tools
Raw event dumps are slow and expensive to reason about. These tools return a summary — totals, top-N breakdowns, a bucketed timeline, and a small representative sample — instead:
search_logs— the general-purpose version: query + time range in, aggregated summary out.traffic_by_ip/traffic_by_host/traffic_by_path— same aggregation, pre-scoped to one IP/hostname/path.group_by_ip/group_by_path/group_by_user_agent— facet counts only (thin wrappers overfield_facets), for when you just need a breakdown, not the full aggregate.timeline— bucketed counts over a range, computed client-side via repeated/apiv2/events/countcalls (Loggly'svolume-metricsendpoint doesn't accept a free-text query, so this is the only way to get a timeline for an arbitrary search).sample_events— a handful of representative raw events, when you need examples rather than the complete result set.
Field naming depends on how each Loggly source parses its logs, and can differ between accounts
and even between tags within one account — so these tools resolve field names discovery-first:
for any role not explicitly overridden (host_field/path_field/status_field/user_agent_field/
ip_field arguments, or the LOGGLY_FIELD_HOST/_PATH/_STATUS/_USER_AGENT/_IP env vars),
they check /apiv2/fields/ for the actual query and match candidates against known role patterns:
Exactly one match → used automatically, reported under
discovered_fieldsin the result.Multiple plausible matches (e.g. a source with both
ClientIpandCustIP) → never guessed between — reported underambiguous_fieldsinstead, falling back to the configured default. Pass the correct one explicitly via the matching*_fieldargument.No match → falls back to the configured default (
host,path,status,user_agent,ip).
Run list_fields yourself if you want to see every candidate before deciding on an override.
IP Intelligence
rdap_lookup— IP ownership/network registration (RIR, netblock, org, country) via public RDAP (rdap.org). No API key required.ip_reputation— GreyNoise (internet-wide scanning noise) + AbuseIPDB (community abuse reports) for an IP. RequiresGREYNOISE_API_KEY/ABUSEIPDB_API_KEY; either one missing just comes back asavailable: falsefor that source, not an error.get_ip_context— combines all of the above with Loggly traffic (1h/24h/30d counts, first/last seen, hosts, top paths) checked across every configured Loggly account unlessaccountis given, and flagscross_domain_correlationwhen the IP shows activity in more than one account. Per thebot-traffic-triageplaybook, that cross-domain pattern is the single strongest signal for distinguishing targeted reconnaissance from background noise.
Treat all IP-intel output as one input among several — identity/reputation data (who owns an
IP, third-party scanner reports) should carry less weight than behavioral evidence from your own
logs. See the bot-traffic-triage skill for the full investigation methodology.
Logging
Logs are written to stderr to avoid interfering with MCP stdio traffic.
Use LOGGLY_LOG_LEVEL to control verbosity. Default is info.
Timeouts, Retries & Concurrency
Requests enforce a per-call timeout of LOGGLY_REQUEST_TIMEOUT_MS (default 15000).
Transient failures (429, 500 with timeout-like body, 503, 504, or network timeouts) are retried up to LOGGLY_MAX_RETRIES times, honoring a Retry-After header on 429 when Loggly sends one, falling back to exponential backoff otherwise.
The aggregation tools (search_logs, traffic_by_*, get_ip_context, etc.) fan out several requests per call via Promise.all (facets + timeline buckets + a sample). LOGGLY_MAX_CONCURRENT_REQUESTS (default 4) caps how many of those run at once per account, so that fan-out doesn't trip Loggly's own rate limit by itself. If you still see 429s from a single aggregation call, lower this; if Loggly's limit is more generous, raise it.
Tool Manifest
Tool metadata is stored in tool-manifest.json and verified against src/server.js.
npm run verify:manifestSmoke Test
Smoke test runs without Loggly credentials by setting LOGGLY_SMOKE_TEST=1.
npm run smokeImplemented MCP Tools
Low-level Loggly API wrappers:
connection_testcreate_searchget_eventssearch_and_get_eventsiterate_events_pageiterate_events_nextcount_eventsvolume_metricsstats_querylist_fieldsfield_facetsraw_api_call
Aggregation-first traffic tools:
search_logstraffic_by_iptraffic_by_hosttraffic_by_pathgroup_by_ipgroup_by_pathgroup_by_user_agenttimelinesample_events
IP intelligence:
rdap_lookupip_reputationget_ip_context
Examples
Example tool argument payloads are in examples/.
Development
npm testnpm test runs manifest verification and the smoke test. CI runs the same checks in .github/workflows/ci.yml.
Versioning
VERSIONcontains the current release version.CHANGELOG.mdtracks changes by release.
Security Notes
.envfiles must never be committed.Tokens and API keys (
LOGGLY_TOKEN,LOGGLY_ACCOUNTS,GREYNOISE_API_KEY,ABUSEIPDB_API_KEY,MCP_BEARER_TOKEN) are treated as secrets.This server enforces read-only access to Loggly
/apiv2/*endpoints. IP-intel calls (RDAP/GreyNoise/AbuseIPDB) are read-only GET requests to those third-party services; no Loggly credentials are ever sent to them, and no IP-intel keys are sent to Loggly.
Available Tools
24 toolsconnection_testConnection TestB
Validates Loggly credentials by creating a small search and returning the RSID.
Inputs: from, size, query, until, +1 more.
count_eventsCount EventsD
Calls /apiv2/events/count to return event count and optional volume.
Inputs: from, query, until, account, +1 more.
create_searchCreate SearchC
Creates a Loggly search and returns its RSID metadata.
Inputs: from, size, order, query, +2 more.
field_facetsField FacetsC
Calls /apiv2/fields// to return terms and counts for a specific field.
Inputs: field_name (required), from, query, until, +2 more.
get_eventsGet EventsC
Retrieves event results for a previously-created RSID from /apiv2/events.
Inputs: rsid (required), page, format, account, +1 more.
get_ip_contextGet IP ContextB
Combines RDAP, GreyNoise/AbuseIPDB reputation, and Loggly traffic (1h/24h/30d counts, first/last seen, hosts, top paths — checked across every configured Loggly account unless account is given) into one normalized profile for an IP. Flags cross_domain_correlation when the IP shows activity in more than one account, which the bot-traffic-triage playbook treats as the single strongest escalation signal.
Inputs: ip (required), account, ip_field, host_field, +1 more.
group_by_ipGroup By IPC
Facet counts by IP for a query/time range (thin wrapper over field_facets).
Inputs: query, window, account, ip_field, +1 more.
group_by_pathGroup By PathC
Facet counts by path for a query/time range (thin wrapper over field_facets).
Inputs: query, window, account, facet_size, +1 more.
group_by_user_agentGroup By User AgentB
Facet counts by User-Agent for a query/time range (thin wrapper over field_facets).
Inputs: query, window, account, facet_size, +1 more.
ip_reputationIP ReputationA
Checks GreyNoise (internet-wide scanning noise) and AbuseIPDB (community abuse reports) for an IP. Requires GREYNOISE_API_KEY / ABUSEIPDB_API_KEY env vars — returns available:false for whichever isn't configured, rather than erroring.
Inputs: ip (required).
iterate_events_nextIterate Events NextA
Fetches the next page from /apiv2/events/iterate using the exact next URL returned by the previous page.
Inputs: next_url (required), account.
iterate_events_pageIterate Events PageC
Calls /apiv2/events/iterate with query parameters and returns the first page plus next URL.
Inputs: from, size, order, query, +2 more.
list_fieldsList FieldsC
Calls /apiv2/fields/ to return parsed field names in the selected time range.
Inputs: from, query, until, account, +1 more.
raw_api_callRaw API CallC
Makes a GET request to a Loggly API path. Useful while discovering exact endpoint behavior.
Inputs: path, account, paramsJson.
rdap_lookupRDAP LookupC
Looks up IP ownership/network registration data (RIR, netblock, org, country) via public RDAP (rdap.org) — no API key required.
Inputs: ip (required).
sample_eventsSample EventsA
Returns a small number of representative events for a query — use this instead of pulling full result pages when you just need examples, not the complete set.
Inputs: from, limit, order, query, +2 more.
search_and_get_eventsSearch And Get EventsC
Creates a search then fetches one page from legacy /apiv2/events using the returned RSID.
Inputs: from, page, size, order, +5 more.
search_logsSearch Logs (Aggregated)A
Runs a query and returns an aggregated summary (total, top hosts/paths/status codes/user agents, a bucketed timeline, and a small representative sample) instead of raw events. Prefer this over get_events/iterate_events_* for exploratory analysis.
Inputs: from, query, top_n, until, +7 more.
stats_queryStats QueryC
Calls /apiv2/stats/<stat_type>/ for numeric field statistics.
Inputs: field (required), stat_type (required), from, query, +2 more.
timelineTimelineC
Bucketed event counts over a time range for a query, computed client-side from /apiv2/events/count.
Inputs: from, query, until, account, +1 more.
traffic_by_hostTraffic By HostC
Aggregated traffic summary (see search_logs) scoped to a single hostname.
Inputs: hostname (required), top_n, window, account, +3 more.
traffic_by_ipTraffic By IPC
Aggregated traffic summary (see search_logs) scoped to a single IP address.
Inputs: ip (required), top_n, window, account, +3 more.
traffic_by_pathTraffic By PathC
Aggregated traffic summary (see search_logs) scoped to a single request path.
Inputs: path (required), top_n, window, account, +3 more.
volume_metricsVolume MetricsC
Calls /apiv2/volume-metrics to retrieve count/volume grouped or filtered by host/app/log type/tag.
Inputs: app, from, host, until, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
There is real overlap: get_events, search_and_get_events, iterate_events_page/next, search_logs, and sample_events all retrieve event data, and the traffic_by_*/group_by_* families are near-identical variants differing only by dimension (some explicitly 'thin wrappers over field_facets'). The descriptions do provide guidance ('prefer this over...'), which prevents outright confusion, but an agent must read carefully to pick correctly.
All names use snake_case and are largely verb_noun or noun_verb forms (create_search, get_events, count_events, list_fields, sample_events, rdap_lookup). A few noun-first names (volume_metrics, field_facets, traffic_by_ip, timeline) deviate from the verb-first majority but remain readable and predictable.
24 tools is on the heavy end for a log-search server, and several families are redundant (traffic_by_ip/host/path, group_by_ip/path/user_agent) and could be collapsed into parameterized tools. It's justifiable but feels inflated by wrapper duplication.
The surface covers the core Loggly lifecycle well: credential check, search creation, event retrieval/iteration, counts, volume, stats, field listing/facets, plus aggregation helpers and external IP enrichment (RDAP, GreyNoise, AbuseIPDB, combined context). Minor gaps like saved-search management or write/delete operations exist but are outside the apparent read-only analytics scope.
Maintenance
Related MCP Connectors
Free, read-only public-source threat intel over MCP. No account or API key.
Free MCP server of security & dev API tools -- supply-chain, CVE, DNS, WHOIS, OFAC, Cosmos SDK.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Related MCP Servers
- AlicenseBqualityDmaintenanceA read-only MCP server for OpenObserve Community Edition that works over the REST API. Provides tools for searching logs, traces, stream schemas, and dashboards - no Enterprise license required.873 PyPI16GPL 3.0
- AlicenseAqualityBmaintenanceMCP server for Malcolm (Zeek/Suricata/Arkime/OpenSearch/NetBox): full read surface plus opt-in, audited write tools.5180 PyPI2MIT
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for Elasticsearch log querying. Enables natural language search, filtering, context retrieval, and aggregation of logs.-
- AlicenseAqualityDmaintenanceRead-only MCP server for the SentinelOne management API, exposing sites, endpoint agents, threats, and activity logs with aggregation tools for MSP/MSSP reporting.612 npmMIT