Create a new, empty in-memory Maltego graph and make it active.

The graph lives in server memory until you save it with maltego_save_graph, which writes a .mtgx file that opens in Maltego CE. Subsequent entity/link operations target the active graph.

Args: params (CreateGraphInput): - name (str): Unique name for the new graph.

Returns: str: Confirmation message including the graph name.

Open an existing Maltego .mtgx file into memory and make it active.

Parses the GraphML inside the archive into entities and links so they can be inspected and edited. The graph remembers its source path so maltego_save_graph can re-save in place.

Args: params (OpenGraphInput): - path (str): Path to an existing .mtgx file.

Returns: str: Summary of the loaded graph (entity/link counts) or an error.

Save a graph to a Maltego .mtgx file that opens in Maltego CE.

Writes the active graph (or the named graph) as a .mtgx archive. If no path is supplied, re-saves to the path the graph was opened from. Open the resulting file in Maltego CE via File > Open, or refresh it if already open.

Args: params (SaveGraphInput): - path (Optional[str]): Destination .mtgx path. Defaults to the graph's original source path. - graph_name (Optional[str]): Graph to save; defaults to active graph.

Returns: str: The absolute path written, or an actionable error.

List all graphs currently open in the server and mark the active one.

Returns: str: Markdown bullet list of open graphs with entity/link counts, or a note if none are open.

Make a previously-opened graph the active target for entity/link operations.

Args: params (SetActiveGraphInput): - name (str): Name of an open graph (see maltego_list_graphs).

Returns: str: Confirmation or an actionable error.

Add an entity (node) to the active graph.

Use this to place domains, IPs, people, emails, etc. on the investigation graph. By default duplicate entities (same type + value) are merged rather than re-created. Unknown maltego.* types are accepted so investigations are never blocked by a missing catalog entry.

Args: params (AddEntityInput): - type (str): Maltego entity type id (e.g. 'maltego.Domain'). - value (str): Primary value (e.g. 'example.com'). - properties (Optional[Dict[str,str]]): Extra properties. - notes (Optional[str]): Free-text notes. - dedupe (bool): Reuse existing identical entity (default True).

Returns: str: Confirmation including the new (or existing) entity id, plus a hint if the entity type is not in the known catalog.

Add a directed link (edge) between two existing entities on the active graph.

Args: params (AddLinkInput): - source_id (str): Source entity id (e.g. 'n0'). - target_id (str): Target entity id (e.g. 'n1'). - label (Optional[str]): Label drawn on the link.

Returns: str: Confirmation including the new link id, or an actionable error if an endpoint id does not exist.

List entities on the active graph, with optional filtering and pagination.

Args: params (ListEntitiesInput): - type_filter (Optional[str]): Restrict to a Maltego type. - value_contains (Optional[str]): Case-insensitive substring filter. - limit (int): Max results (1-500, default 50). - offset (int): Results to skip (default 0). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: In JSON form, an object: { "total": int, # entities matching filters "count": int, # entities in this page "offset": int, "has_more": bool, "next_offset": int | None, "entities": [ {id, type, value, properties, notes, weight}, ... ] } In markdown form, a readable bullet list.

Fetch full details of one entity on the active graph by id.

Args: params (GetEntityInput): - entity_id (str): Entity id (e.g. 'n0'). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Entity detail. JSON form is {id, type, value, properties, notes, weight}; markdown form is a readable block. Error if the id is unknown.

Update an entity's value, properties, notes, or weight on the active graph.

Only the supplied fields change; properties are merged (not replaced).

Args: params (UpdateEntityInput): - entity_id (str): Entity to update. - value (Optional[str]): New primary value. - properties (Optional[Dict[str,str]]): Properties to set/merge. - notes (Optional[str]): Replacement notes. - weight (Optional[int]): Node weight (0-100).

Returns: str: Confirmation or an actionable error.

Delete an entity and all links touching it from the active graph.

Args: params (DeleteEntityInput): - entity_id (str): Entity to delete.

Returns: str: Confirmation including how many links were removed, or an error.

List supported Maltego entity types from the built-in catalog.

Use this to discover valid type ids for maltego_add_entity. The catalog is a curated subset of Maltego's built-in types; custom types also work.

Args: params (ListEntityTypesInput): - category (Optional[str]): Filter to one category (e.g. 'infrastructure', 'personal', 'social', 'organization', 'location').

Returns: str: Markdown grouped by category, listing each type id and its main property.

List available transforms, optionally filtered by accepted input type.

Transforms expand an entity into related entities (e.g. a domain into its IP addresses). The built-in 'local' provider needs no API keys; more providers (a Maltego API, OSINT services) can be added without changing these tools.

Args: params (ListTransformsInput): - input_type (Optional[str]): Only transforms accepting this type.

Returns: str: Markdown list of transforms with name, accepted input types, output types, provider, and whether they require network access.

Run a transform on an entity in the active graph to discover related entities.

Looks up the named transform, runs it against the given input entity, and (by default) adds the resulting entities to the active graph with links back to the input entity. Results are de-duplicated against existing entities.

Args: params (RunTransformInput): - transform_name (str): Transform to run (see maltego_list_transforms). - entity_id (str): Input entity id in the active graph. - add_to_graph (bool): Add results to the graph (default True).

Returns: str: Summary of discovered entities (and the ids created when added), or an actionable error (unknown transform, type mismatch, no results).

Automatically investigate a domain by adding it and running transforms.

A one-call workflow: ensures an active graph (creating one if needed), adds a Domain entity, then expands the graph by running every applicable + available transform (DNS, plus any configured OSINT providers) for a few rounds, de-duplicating results. Use this instead of chaining transforms manually.

Args: params (InvestigateInput): - value (str): The domain to investigate (e.g. 'example.com'). - allow_network (bool): Run network transforms (default True). - max_rounds (int): Expansion depth 1-4 (default 2).

Returns: str: Summary of how many transforms ran and what was discovered, plus a note of any transforms skipped for missing API keys.

Automatically investigate an email address (domain, breaches, footprint).

Adds an Email Address entity and expands the graph: derives the domain, checks breach exposure (if a HaveIBeenPwned key is configured), and expands the related domain's basic footprint. See maltego_investigate_domain for the shared behaviour and return shape.

Args: params (InvestigateInput): - value (str): The email to investigate (e.g. 'bob@example.com'). - allow_network (bool): Run network transforms (default True). - max_rounds (int): Expansion depth 1-4 (default 2).

Returns: str: Summary of what was discovered.

Automatically investigate an IPv4 address (reverse DNS, ports, services).

Adds an IPv4 Address entity and expands the graph using reverse DNS plus any configured host-intelligence providers (Shodan, Censys). See maltego_investigate_domain for the shared behaviour and return shape.

Args: params (InvestigateInput): - value (str): The IPv4 address (e.g. '8.8.8.8'). - allow_network (bool): Run network transforms (default True). - max_rounds (int): Expansion depth 1-4 (default 2).

Returns: str: Summary of what was discovered.

Load an existing .mtgx file as a new active graph (continue an investigation).

Equivalent to maltego_open_graph: parses all entities, links, properties, and any stored layout positions so you can continue editing and re-save (full round-trip).

Args: params (LoadGraphInput): - path (str): Path to the .mtgx file.

Returns: str: Summary of the loaded graph, or an actionable error.

Merge a .mtgx file's contents into the ACTIVE graph (combine investigations).

Unlike maltego_load_graph (which opens a separate graph), this merges another graph's entities and links into the current active graph, remapping ids and de-duplicating by (type, value) when dedupe is true.

Args: params (ImportGraphInput): - path (str): Path to the .mtgx file to merge in. - dedupe (bool): Reuse matching entities instead of duplicating.

Returns: str: Counts of entities/links added and reused, or an actionable error.

Summarize the active investigation graph (composition + key entities).

Deterministic overview: entity/link totals, a breakdown by entity type, the most-connected entities, and any isolated entities. Ideal for presenting an investigation's state to a user.

Args: params (SummarizeGraphInput): - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: JSON form matches analysis.summarize_graph (name, entity_count, link_count, type_breakdown, most_connected, isolated_count, isolated); markdown form is a readable brief.

Explain one entity: its data, neighbours, and how it can be expanded.

Deterministic context for a single node: properties, notes, degree, incoming and outgoing neighbours (with link labels), and which transforms apply to it (and whether each is currently available).

Args: params (ExplainEntityInput): - entity_id (str): Entity id (e.g. 'n0'). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Detailed explanation, or an error if the id is unknown.

Identify the most promising pivot entities in the active graph.

Deterministically ranks entities that connect many others (degree >= 2), which are typically the best points to pivot an investigation (shared IPs, central emails, etc.).

Args: params (AnalysisLimitInput): - limit (int): Max pivots to return (1-50, default 10). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Ranked pivots with id, value, type, degree, and a reason.

Legacy simple heuristic for next transforms — prefer maltego_next_best_actions.

Use when: you want the basic heuristic list. For real recommendations use maltego_next_best_actions (memory-aware, ranked, explainable). Kept for backward compatibility.

Deterministically recommends transforms to advance the investigation, prioritising the most-connected entities and available transforms first. Unavailable (missing-key) transforms are still listed but flagged.

Args: params (AnalysisLimitInput): - limit (int): Max suggestions (1-50, default 10). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Suggestions of (transform, target entity, expected output types).

Compute and assign (x, y) layout positions to entities on the active graph.

Positions are stored on the graph and persisted into the .mtgx on save. Re-run after adding entities to refresh the layout. Layouts are deterministic.

Args: params (ApplyLayoutInput): - algorithm (str): 'hierarchical', 'radial', or 'force'.

Returns: str: Confirmation with the number of entities positioned.

Build entities (and optional links) on the active graph from CSV.

Accepts a CSV file path or raw CSV text with a 'type,value' header (optional 'notes' and 'link_to' columns). The 'type' column accepts friendly aliases ('Domain', 'Email', 'IP') or full Maltego type ids. Entities are deduplicated; rows with unknown types are skipped and reported.

Args: params (ImportCsvInput): - path (Optional[str]): Path to a CSV file, OR - content (Optional[str]): Raw CSV text.

Returns: str: Counts of entities added/reused, links added, rows skipped, and any per-row warnings.

List OSINT transform providers and whether each is configured.

Shows the built-in 'local' provider plus external providers (VirusTotal, Shodan, SecurityTrails, Censys, Hunter.io, HaveIBeenPwned), the environment variable(s) each needs, and whether those are currently set.

Returns: str: Markdown list grouped by tier with configuration status and the env vars required to enable each provider.

Generate a deterministic investigation report for the active graph.

The report includes an executive summary, key findings (pivots), an entity inventory by type, relationship highlights, and suggested next steps. Returns the report text inline (use maltego_export_report to write it to a file).

Args: params (GenerateReportInput): - format (ReportFormat): 'markdown' (default) or 'html'.

Returns: str: The full report as Markdown or HTML text.

Write a deterministic investigation report for the active graph to a file.

Same content as maltego_generate_report, written to path. Use a .md path for markdown or .html for HTML.

Args: params (ExportReportInput): - path (str): Destination file path. - format (ReportFormat): 'markdown' (default) or 'html'.

Returns: str: Confirmation including the path written.

List available investigation machines (reusable workflow templates).

Machines run a curated set of transforms over several rounds (e.g. 'Passive Domain Investigation'). Run one with maltego_run_machine.

Returns: str: Markdown list of machines with their seed type and description.

Run an investigation machine against a seed value on the active graph.

Ensures an active graph (creating one if needed), seeds the machine's entity type with seed_value, and expands the graph per the machine's recipe. Missing/unavailable transforms are skipped gracefully.

Args: params (RunMachineInput): - machine_name (str): e.g. 'passive_domain' (see maltego_list_machines). - seed_value (str): Seed value (domain/email/ip). - allow_network (Optional[bool]): Override the machine's network setting. - max_rounds (Optional[int]): Override expansion depth.

Returns: str: Summary of what the machine discovered, or an actionable error.

List recorded investigation steps (procedural memory) for the active graph.

Each step records a transform execution: what ran, why, the trigger entity, what it discovered, status, and importance. This is the investigation's reasoning trace, not just its data.

Args: params (ListStepsInput): - limit/offset (int): Pagination. - status (Optional[str]): Filter by 'success', 'empty', or 'error'. - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: JSON form is {total, count, offset, steps:[...]}; markdown is a list.

Explain why an entity is on the graph: which step/transform discovered it.

Uses Investigation Memory to trace an entity's provenance — the transform that produced it, the entity that triggered that transform, and the recorded reason. Seed entities (added manually or via CSV) report as analyst-provided.

Args: params (ExplainWhyInput): - entity_id (str): Entity id (e.g. 'n3'). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Provenance explanation, or an error if the id is unknown.

Explain one recorded transform execution by its execution id.

Args: params (ExplainTransformInput): - transform_execution_id (str): e.g. 'x0' (see maltego_list_investigation_steps). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Full step detail, or an error if the execution id is unknown.

Return the chronological timeline of the active investigation.

A compact, ordered narrative of every transform execution recorded in Investigation Memory — useful for review, audit, and explaining the path the investigation took.

Returns: str: Markdown timeline (one line per step in execution order).

Recommend the most valuable next moves (decision engine). Use when deciding what to do next.

A deterministic, explainable ranking that weighs entity importance, expected information gain, confidence, provider availability, and — crucially — the Investigation Memory (so it never re-suggests a transform already attempted on an entity). Supersedes maltego_suggest_next_steps with richer reasoning.

Args: params (AnalysisLimitInput): - limit (int): Max recommendations (1-50, default 10). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Ranked recommendations, each with transform, target entity, a deterministic score, expected gain, and a plain-English reason.

PRIMARY entry point — run a COMPLETE investigation in one call.

Use when the user wants to investigate anything (domain, email, IPv4/IPv6, or URL, or a bare value). This is the default for "investigate X". It auto-detects the type, builds/expands the graph via the right machine (recording Investigation Memory), lays it out, summarizes, scores/ranks entities, computes next-best-actions, and includes an inline report — and returns ONE finished briefing. Present it directly; do not call summarize/ list/suggest afterwards. Next: offer to maltego_save_graph or maltego_export_report (do not write files unless asked).

Args: params (InvestigateQueryInput): - query (str): What to investigate (type auto-detected). - allow_network (bool): Run network transforms (default True). - depth (str): 'quick' | 'standard' (default) | 'deep'. 'deep' runs ALL applicable available transforms over more rounds (thorough, slower); use it when the user asks to "go deep"/"dig further". - max_rounds (Optional[int]): Explicit rounds override (else set by depth). - layout (str): 'hierarchical' | 'radial' | 'force'. - include_report (bool): Append the full inline report (default True). - include_next_actions (bool): Include NBA recommendations (default True).

Returns: str: One complete briefing — detection + run stats, important discoveries, recommended next actions, and (by default) a full inline report. No files are written.

Enable real-time investigation mode and return a subscription id.

Turns on the event bus's live mode and buffering. Because MCP stdio cannot push to the caller, retrieve emitted events by polling maltego_get_recent_events (events are also buffered before subscribing). Real-time mode is optional and does not change any .mtgx behaviour.

Returns: str: The subscription id and current buffer/sequence state.

Return recent investigation events (entity_discovered, transform_*, etc.).

Reads from the event bus's bounded buffer. Use since_seq to fetch only events newer than a sequence number you've already seen (incremental polling).

Args: params (GetEventsInput): - limit (int): Max events (default 50). - since_seq (Optional[int]): Only events with seq greater than this. - response_format (ResponseFormat): 'json' (default) or 'markdown'.

Returns: str: JSON form is {count, next_seq, events:[{seq,type,timestamp,data}]}; markdown is a readable list.

Compute intelligence-quality scores for one entity (deterministic).

Returns confidence, source_reliability, linkage_strength, investigation_priority, and novelty in [0, 1], derived from the graph structure and Investigation Memory (which providers found the entity).

Args: params (ScoreEntityInput): - entity_id (str): Entity id (e.g. 'n0').

Returns: str: JSON object {entity, scores:{confidence, source_reliability, linkage_strength, investigation_priority, novelty}}.

Rank entities by investigation priority (deterministic).

Scores every entity and returns them ordered by investigation_priority, so an analyst can focus on the most meaningful findings first.

Args: params (RankEntitiesInput): - limit (int): Max entities (1-200, default 20). - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: Ranked entities with their scores.

Explain how an entity's intelligence-quality scores were derived.

Returns the scores plus a deterministic, human-readable rationale (sources, connectivity, type rarity, enriching properties).

Args: params (ScoreEntityInput): - entity_id (str): Entity id (e.g. 'n0').

Returns: str: Markdown explanation with the scores and contributing factors.

Export the active graph's entities to a CSV file (round-trips with import).

Writes the same type,value,notes,link_to schema that maltego_import_csv reads, so an exported CSV can be re-imported to reconstruct entities and their relationships.

Args: params (ExportPathInput): - path (str): Destination CSV file path.

Returns: str: Confirmation including the path and entity count.

Export the full active graph (entities, links, memory, scores) as JSON.

A complete, programmatic snapshot — a superset of the .mtgx sidecars — useful for downstream tooling that doesn't read Maltego files.

Args: params (ExportPathInput): - path (str): Destination JSON file path.

Returns: str: Confirmation including the path.

List links (edges) on the active graph, with pagination.

Args: params (ListLinksInput): - limit/offset (int): Pagination. - response_format (ResponseFormat): 'markdown' (default) or 'json'.

Returns: str: JSON form is {total, count, offset, links:[{id,source,target,label}]}; markdown shows source → target with labels and entity values.

Delete a single link (edge) from the active graph by id.

Args: params (DeleteLinkInput): - link_id (str): Link id (e.g. 'e0'; see maltego_list_links).

Returns: str: Confirmation, or a note if the link id was not found.

Rename an open graph (defaults to the active graph).

Args: params (RenameGraphInput): - new_name (str): New name. - graph_name (Optional[str]): Graph to rename; defaults to active.

Returns: str: Confirmation, or an actionable error (unknown/duplicate name).

Remove an open graph from the server's memory.

This does NOT delete any saved .mtgx file on disk — only the in-memory copy. If the active graph is removed, another open graph becomes active (if any).

Args: params (DeleteGraphInput): - name (str): Name of the open graph to remove.

Returns: str: Confirmation, or an actionable error if the name is unknown.

Show cross-investigation learning stats used by the Next Best Action engine.

Learning is opt-in: enable it by setting the env var MALTEGO_MCP_LEARNING=1 (or MALTEGO_MCP_LEARNING_PATH=/path/to/file.json). When enabled, the engine records per-transform outcomes across investigations (runs, successes, average yield) and lets that history nudge recommendations.

Returns: str: JSON of per-transform stats, or a note if learning is disabled.

Clear the cross-investigation learning store (in-memory and on disk).

No-op when learning is disabled.

Returns: str: Confirmation.

Run ALL applicable, available transforms on ONE entity to pivot from it.

Use when: you want to dig into a specific node (e.g. a pivot from maltego_identify_pivots) rather than re-running a whole investigation. Records Investigation Memory and links results back to the entity.

Args: params (ExpandEntityInput): - entity_id (str): Entity to expand (e.g. 'n0'). - allow_network (bool): Run network transforms (default True). - max_rounds (int): Expansion rounds from this entity (1-4, default 1).

Returns: str: Summary of what the expansion discovered.

Find the shortest relationship path between two entities (undirected BFS).

Use when: you want to know how two findings are connected (e.g. does this email relate to that IP, and through what?).

Args: params (FindPathInput): - source_id (str): Start entity id. - target_id (str): End entity id.

Returns: str: The shortest path as a chain of entities (with link labels), or a note if no path exists.

Return how to use this server: the autonomous workflow and the tool map.

Use when: you are unsure which tool to call or how the investigation flow works. This is the same guidance the server provides as MCP instructions — call it to pull the workflow into context. Next: usually maltego_investigate.

Returns: str: The full usage guidance (workflow, tool map, conventions).