tenable-activity-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tenable-activity-mcp Summarize activity over the past 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tenable-activity-mcp
An MCP server that exposes the Tenable Vulnerability Management audit/activity log
(GET /audit-log/v1/events) as a small set of tools, so any MCP client can ask about
platform activity, API-key usage, and anomalous behaviour on demand.
The server does the analysis. Counting, grouping, rate math and threshold comparisons
all happen in Python; tools return finished, structured results (failure_rate_pct,
by_actor, findings with reasoning) rather than dumping raw events for the model to
add up.
What it gives you
Tool | Purpose |
| Event feed for a window, with actor/action filters. Pagination is followed automatically; returns a resumable |
| Deterministic rollup for a window: counts by actor, action, CRUD type and access type, plus failure/anonymous rates. |
| API-key-driven activity only, grouped by actor: action breakdown, distinct source IPs, first/last seen. |
| Compares a window against each actor's stored baseline. Flags new actors, volume spikes, unseen source IPs, failed-event bursts, sustained failure rates, off-hours spikes and never-before-seen actions - each with evidence and a reasoning sentence. |
| One actor's full picture: role (best effort), all-time action breakdown, access types, every source IP seen. |
| Pass/fail on whether the configured keys can actually read the audit log, with remediation text. |
Safety properties worth knowing:
Nothing that looks like a credential is ever returned. Field values whose key names a secret (
secret_key,api_key,token,password, ...) or whose value looks like Tenable key material are masked to their last 4 characters.Pagination is capped at 20 pages / 100k events per tool call; hitting the cap is reported explicitly along with the cursor needed to continue.
429s back off using the
X-RateLimit-Resetheader (the endpoint sends noRetry-After), with exponential fallback and a retry ceiling.
Related MCP server: tenable-mcp-server
Requirements
Python 3.11+
Tenable VM API keys whose owner can read the audit log
Tenable role / permissions
Reading audit-log/v1/events requires the Administrator role, or a custom role with
explicit audit-log read permission, on the user that owns the API keys. Anything less
gets HTTP 403; check_permission_prereqs reports that in plain language.
Generate keys in Tenable VM under Settings → My Account → API Keys. The keys inherit the permissions of the user that created them.
get_actor_profile additionally tries to resolve an actor's role from the user
directory. If the keys cannot list users, the profile is still returned - just without
the role label.
Setup
uv sync --extra devThen copy .env.example to .env and fill in your keys:
cp .env.example .envVerify credentials and permissions before wiring it into a client:
uv run python -c "from dotenv import load_dotenv; load_dotenv(); from src.server import check_permission_prereqs; print(check_permission_prereqs())"Run the server directly (it speaks MCP over stdio, so it will just sit there waiting for a client - that is the correct behaviour):
uv run python -m src.serverConnecting a client
Use the absolute path to your clone in the config below. To print it, run pwd
from the repository root on macOS/Linux, or (Get-Location).Path in PowerShell.
Claude Desktop
Edit claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tenable-activity": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\tenable-activity-mcp",
"run",
"python",
"-m",
"src.server"
],
"env": {
"TENABLE_ACCESS_KEY": "your_access_key",
"TENABLE_SECRET_KEY": "your_secret_key",
"TENABLE_MCP_BASE_URL": "https://cloud.tenable.com"
}
}
}
}Restart Claude Desktop afterwards. On macOS/Linux use a POSIX path
(/Users/you/tenable-activity-mcp).
If uv is not on the launcher's PATH, use its absolute path (which uv /
(Get-Command uv).Source) as command.
Claude Code
claude mcp add tenable-activity --env TENABLE_ACCESS_KEY=your_access_key --env TENABLE_SECRET_KEY=your_secret_key -- uv --directory /absolute/path/to/tenable-activity-mcp run python -m src.serverOr add the same block as above to a project-level .mcp.json.
Credentials passed via env take precedence over .env; the .env file is a
local-development convenience, and either mechanism works.
Example questions to ask once connected
"Check whether my Tenable credentials can read the audit log."
"Summarise Tenable platform activity for the last 7 days - who was most active, and what's the failure rate?"
"Which API keys were used against Tenable in the last 30 days, and from which source IPs?"
"Look for anomalies in Tenable activity over the past 3 days against a 30-day baseline, and explain anything you flag."
"Show me everything actor 00000000-1111-4222-8333-444444444444 has ever done - actions, access types, and IPs."
How anomaly detection works
detect_anomalies needs history to compare against, which lives in a local SQLite file
(state.db, created automatically):
If stored baselines are older than
BASELINE_REFRESH_MAX_AGE_HOURS(12), the server fetches thebaseline_daysimmediately preceding your window and recomputes per-actor averages, known IPs, known actions and an hour-of-day histogram.Your window is fetched and compared against those baselines.
Events in the analysed window are not folded into the baseline, so re-running the same window returns the same findings.
Every threshold is a named constant at the top of src/anomaly.py and is echoed back in
each result under thresholds:
Constant | Default | Meaning |
|
| Window events/day must exceed this multiple of the baseline average |
|
| Floor before a spike can be flagged at all |
|
| How recently an IP must have been seen to count as "known" |
|
| Failure-clustering trigger |
|
| Sustained failure-rate trigger (over at least 10 events) |
|
| Off-hours band |
|
| Off-hours share must exceed this multiple of the actor's baseline share |
Baselines are per actor, so a service account that legitimately runs 500 scans a day does not get flagged for doing exactly that.
Layout
src/
server.py MCP entrypoint (FastMCP-style) + the six tool definitions
tenable_client.py Auth, filter building, cursor pagination, 429 backoff, typed errors
classifier.py API-key vs UI/session tagging, IP extraction, redaction, rollups
anomaly.py Thresholds and the individual anomaly checks
state.py SQLite: cursors, accumulated actor history, computed baselines
tests/
test_pagination.py test_classifier.py test_anomaly.pyDependency direction is one-way: server → {anomaly, classifier, state} → tenable_client.
Testing
Three levels, in the order you should run them.
1. Unit tests (no credentials, no network)
uv run pytest -q105 tests covering pagination/cursor handling, rate-limit backoff, API-key vs session classification, redaction, and every anomaly threshold. Every API response is faked through a stub transport, so the suite never touches a live tenant.
2. Offline end-to-end (no credentials, no network)
uv run python scripts/smoke_local.pyRuns all six tools against a scripted fake Tenable (a quiet baseline month, then a noisy night from a new IP) and asserts the results: anomalies flagged, planted secrets redacted, bad input returned as a structured error instead of an exception. Exits non-zero on any failure, so it works as a pre-commit or CI gate.
3. Live check against your tenant (read-only)
With .env filled in:
uv run python scripts/live_check.py 7Verifies audit-log permissions first and stops with remediation text if they are wrong, then prints a real summary, API-key usage breakdown, anomaly findings, and the busiest actor's profile for the last N days (default 7). All calls are GETs; nothing is written to Tenable.
4. Through an MCP client
Any MCP client works. To poke at the tools interactively without a chat client:
npx @modelcontextprotocol/inspector uv --directory . run python -m src.serverOr wire it into Claude Desktop / Claude Code (above) and ask one of the example
questions. check_permission_prereqs is the right first call - it confirms the server
started, found its credentials, and can reach the audit log.
Inspecting local state
uv run python -c "from src.state import StateStore; print(StateStore().stats())"Delete state.db to reset baselines; the next detect_anomalies call rebuilds them.
Known limitations
Requires the Administrator role. Reading
audit-log/v1/eventsneeds the Administrator role, or a custom role with explicit audit-log read permission, on the user that owns the API keys. Anything less returns HTTP 403. Runcheck_permission_prereqsfirst - it reports exactly this, with remediation text.Anomaly detection needs history before it is useful. The first
detect_anomaliescall against a freshstate.dbbuilds baselines from the 30 days preceding your window and then compares against them. Actors with little or no prior activity flag asnew_actor, so early runs are noisier than later ones.Role resolution is best effort.
get_actor_profiletries to resolve an actor's Tenable role from the user directory. If the keys cannot list users, the profile is still returned - just without the role label.Off-hours detection uses a fixed UTC band. The off-hours window is 20:00-06:00 UTC and does not adjust to the tenant's working timezone. Distributed teams will see off-hours findings that are simply another region's working morning.
Baselines are local to the machine running the server.
state.dbis not shared between installs, so two operators running their own copies build independent baselines and can reach different conclusions about the same window.Wide windows return partial results by design. One tool call follows at most 20 pages / 100,000 events. Hitting that cap is reported explicitly along with the
next_tokenneeded to resume, so it is never a silent truncation - but a very large window does take several calls.Only the first 1,000 events come back inline.
list_activity_eventscaps the inlineeventsarray at 1,000 and setsinline_truncatedwhen it does. Thesummaryblock still covers every event fetched, so the aggregate numbers stay correct even when the inline list is trimmed.get_actor_profilelooks back 365 days at most, and cannot see further back than the audit log itself retains.
Notes
Built against
mcp==2.0.0, where the SDK renamedFastMCPtoMCPServer.server.pyimports whichever name the installed SDK provides, so it also works onmcp1.x.Event fetching goes through pyTenable's
TenableIOsession (audit_log.events(..., return_json=True)), which keeps auth and connection handling in the maintained library while leaving thepagination.nextcursor visible to us. If pyTenable is unavailable, an equivalentrequeststransport using theX-ApiKeys: accessKey=...;secretKey=...header takes over.Timestamps are UTC everywhere, including the off-hours band.
state.dbaccumulates per-actor history. Delete it to reset all baselines; the nextdetect_anomaliescall rebuilds them.
Available Tools
6 toolscheck_permission_prereqsA
Verify the configured API keys can actually read the audit log.
Makes one minimal audit-log request and reports pass/fail with a plain explanation and remediation steps. Run this first when another tool returns an authentication or permission error. No secret material is echoed - the access key is shown with only its last 4 characters.
Returns:
A dict with ok, a human-readable message, remediation when
failing, plus configuration and local-state diagnostics.
Inputs: no named parameters. Returns: object
detect_anomaliesA
Compare a window against each actor's stored baseline and flag outliers.
Checks run: previously unseen actor, event volume above SPIKE_MULTIPLIER x
the actor's historical daily average, source IPs absent from the baseline
lookback, failed-event bursts, sustained high failure rate, off-hours
activity spikes, and never-before-seen action types. Every finding includes
the observed value, the threshold crossed, and a reasoning sentence.
Baselines live in the local SQLite state file and are refreshed from the period immediately preceding the window when they are stale. Events in the analysed window itself are not folded into the baseline, so re-running the same window yields the same findings.
Args: date_from: Start of the window under investigation, ISO-8601. date_to: End of the window under investigation, ISO-8601. baseline_days: Days of history preceding the window to baseline against.
Returns:
A dict with findings (severity-ordered, each with evidence and
reasoning), findings_by_type/findings_by_severity counts, and
the active thresholds.
Inputs: date_to (required), date_from (required), baseline_days. Returns: object
get_actor_profileA
Full historical view of one actor: roles, actions, access types, IPs.
Combines a fresh audit-log fetch for the actor with everything previously persisted in the local state database, so IPs and actions seen in earlier sessions still show up. The Tenable role is resolved on a best-effort basis from the user directory and is omitted when the API keys cannot list users.
Args:
actor_id: The actor UUID (as it appears in actor.id on events).
lookback_days: How far back to fetch fresh events for this actor.
Returns:
A dict with identity, recent_activity (rollup over the lookback
window), lifetime (accumulated state: all IPs, all actions, all
access types, first/last seen) and pagination.
Inputs: actor_id (required), lookback_days. Returns: object
get_api_key_usageA
Report API-key-driven activity per actor (UI/session activity excluded).
Events are classified as API-key driven using the audit event's access/auth-method field, falling back to user-agent shape (scripted client vs browser). Each actor gets an action breakdown, distinct source IPs, and first/last seen timestamps - all pre-aggregated.
Args: actor_id: Optional actor UUID. Omit to cover every actor with API-key activity in the window. date_from: Start of the window, ISO-8601. Defaults to 30 days ago. date_to: End of the window, ISO-8601. Defaults to now.
Returns:
A dict with actors (per-actor API-key usage profiles), an
access_type_totals breakdown for context, and coverage metadata.
Inputs: date_to, actor_id, date_from. Returns: object
list_activity_eventsA
List Tenable audit-log events for a date range, with optional filters.
Pagination is handled internally (the next cursor is followed
automatically) up to a safety cap of 20 pages / 100k events per call; if the
cap is hit, pagination.next_token is returned so the next call resumes
exactly where this one stopped. Every event is normalised, tagged with an
access type (API key vs UI session), and has credential-looking field values
redacted to their last 4 characters.
Args:
date_from: Start of the window, ISO-8601 (e.g. "2024-01-01" or
"2024-01-01T00:00:00Z"). Inclusive.
date_to: End of the window, ISO-8601. Inclusive.
actor_id: Optional actor UUID to filter on (actor_id.eq).
action: Optional exact action name, e.g. "user.create" (action.eq).
limit: Page size sent to the API (1-5000).
next_token: Opaque cursor from a previous call, to resume pagination.
Returns:
A dict with events (classified, redacted), a summary rollup of
those events, and a pagination block.
Inputs: date_to (required), date_from (required), limit, action, +2 more. Returns: object
summarize_activityA
Summarise all audit-log activity in a window (counts computed in Python).
Returns event counts by actor, by action, by CRUD type and by access type, plus failure and anonymous rates - all pre-computed. Use these numbers directly; do not re-derive them from raw events.
Args: date_from: Start of the window, ISO-8601. Inclusive. date_to: End of the window, ISO-8601. Inclusive.
Returns:
A dict with a summary block (total_events, by_actor,
by_action, by_crud, by_access_type, failure_rate_pct,
top_failed_actions) and a pagination block describing coverage.
Inputs: date_to (required), date_from (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a clearly different concern: raw event listing, summary rollups, API-key-specific usage, anomaly detection, actor profiling, and prerequisite checks. Even the two aggregation tools (summarize_activity and get_api_key_usage) are separated by access-type scope, and their descriptions reinforce the distinction.
All tool names follow a consistent snake_case verb_noun pattern: list_activity_events, summarize_activity, get_api_key_usage, detect_anomalies, get_actor_profile, check_permission_prereqs. The verbs clearly signal the action and the objects clearly signal the resource or concern, making the set predictable and easy to navigate.
Six tools is well-scoped for an audit-log activity server: two raw/aggregate views, two analysis-focused tools, one deep-dive tool, and one operational prerequisite check. Each tool earns its place without redundancy or bloat.
The tool surface covers the full audit-monitoring lifecycle: listing raw events, summarizing them, isolating API-key usage, detecting anomalies, profiling individual actors, and verifying access prerequisites. The automatic pagination and baseline handling close potential dead ends, so an agent can move from raw data to insight without missing critical operations.
Maintenance
Related MCP Connectors
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
Access New Relic observability data through MCP - query metrics, logs, traces, entities, and more
Read-only access to your Auditon vulnerability scans: findings, endpoints, reports and changes.
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes Azure Log Analytics workspace data with tools for querying AuditLogs and AzureActivity tables, supporting custom KQL queries, time range filters, and pagination.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server for Tenable Vulnerability Management and the Tenable One platform, enabling LLMs to query assets, vulnerabilities, scans, exposure metrics, attack paths, and more via natural language.2MIT
- AlicenseAqualityBmaintenanceEnables read-only querying of Azure Log Analytics and Azure Resource Graph through MCP, supporting KQL queries, workspace discovery, and resource inventory exploration with Azure RBAC authentication.1170 npm2MIT
- FlicenseNot gradedqualityCmaintenanceRead-only MCP server for querying Microsoft Purview unified audit logs across M365 workloads, wrapping the Graph API's asynchronous audit log search.-