memgraph-ingester-tool

Standalone query tools for Memgraph knowledge graphs produced by memgraph-ingester.

This package is the single source of truth for all graph query and formatting logic. It is consumed two ways:

• as a library by memgraph-ingester-mcp, which exposes every method as an MCP tool;
• as a CLI (mgtools) for users who work with mgconsole or scripts and have no MCP client.

Any change to query logic here automatically reaches both audiences.

Installation

pip install memgraph-ingester-tool
# or
uv tool install memgraph-ingester-tool

Configuration

Settings come from environment variables. MEMGRAPH_TOOLS_* take priority; MEMGRAPH_INGESTER_MCP_* are accepted as a fallback so existing MCP configurations keep working.

Endpoints

Every endpoint below is exposed twice from the same implementation: as a public method on MemgraphTools and as an mgtools subcommand of the same name. The memgraph-ingester-mcp server registers the identical set as MCP tools.

Code graph endpoints

Memory endpoints

Write operations (memory_upsert, memory_update_status, delete_memory, memory_link_code_ref, memory_refresh_chunk, memory_refresh_embeddings) are rejected when MEMGRAPH_TOOLS_READ_ONLY=true.

CLI usage

Every endpoint above is available as an mgtools subcommand:

# graph inventory, memory counts, vector indexes
mgtools server_status --project my-project

# hybrid vector + lexical code search
mgtools code_search "authentication filter" --project my-project --limit 5

# exact lookups
mgtools code_lookup_methods "GraphWriter.upsertFile" --project my-project
mgtools code_lookup_type --type-name GraphWriter --project my-project

# call graph and refactor impact
mgtools code_callers "GraphWriter.upsertFile" --project my-project
mgtools code_impact "upsertFile" --view files --project my-project

# memory tools
mgtools memory_orientation --project my-project --compact
mgtools memory_search "ingestion pipeline decisions" --project my-project

# read-only Cypher escape hatch (project filter required)
mgtools raw_read_cypher \
  "MATCH (f:File {project: \$project}) RETURN f.path LIMIT 10" \
  --project my-project

Run mgtools --help for the full command list and mgtools <command> --help for per-command options. python -m memgraph_ingester_tool works as well.

Library usage

from memgraph_ingester_tool import MemgraphTools, ToolConfig

tools = MemgraphTools(ToolConfig(default_project="my-project"))
status = tools.server_status()
hits = tools.code_search("authentication filter", limit=5)

MemgraphTools also accepts a pre-built client (anything implementing run(query, parameters, *, write=False)), which is how the MCP server reuses its own connection:

tools = MemgraphTools(config, client=my_client)

Output formats

Row-heavy commands default to table_json — a compact {cols: [...], rows: [...]} encoding. Pass --format json for plain objects. Absent keys mean null or empty, never an error.

Development

uv sync
uv run pytest
uv run ruff check .

License

MIT