Skip to main content
Glama

aleph-mcp

WARNING

This is a Claude one-shot. The whole thing — server, formatters, tests, this README — was written by Claude in a single session, and has had no human review beyond the author reading it over. It works against a live instance (that much was verified), but treat it as a starting point rather than something battle-tested. Read the code before you point it at anything you care about.

A read-only MCP server for Aleph, the open-source investigative data platform that holds leaks, company registries, court records, sanctions lists and document archives. It gives an MCP client ten research tools, built on the official alephclient library.

It talks to any Aleph instance — set ALEPH_HOST. Out of the box it points at OpenAleph, which answers without credentials.

Read-only by design. Every request is a GET. The server cannot create, change or delete anything, and each tool is annotated readOnlyHint so clients can present it as safe.

Quickstart

Drop this in your MCP client's config — no clone, no venv. uvx fetches and runs the server on demand:

{
  "mcpServers": {
    "aleph": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/pkreissel/aleph-mcp", "aleph-mcp"],
      "env": {
        "ALEPH_HOST": "https://search.openaleph.org",
        "ALEPH_API_KEY": ""
      }
    }
  }
}

Leave ALEPH_API_KEY empty and it runs anonymously, which is enough for the default instance (OpenAleph). Point ALEPH_HOST at an instance that needs credentials and paste the key in — that is the only change.

The same thing from the Claude Code CLI:

claude mcp add aleph \
  --env ALEPH_HOST=https://search.openaleph.org \
  --env ALEPH_API_KEY= \
  -- uvx --from git+https://github.com/pkreissel/aleph-mcp aleph-mcp

Then ask your client to search for something. mcp.json in this repo is the same config as a file, with a second entry showing a private instance and an API key. You need uv installed (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh); the first run takes a few seconds to resolve dependencies, later ones are fast.

Related MCP server: opencti-mcp-server

Install

The Quickstart needs none of this. These are the options if you want the server on disk rather than resolved on demand.

Run it without installing (uvx)

uv can fetch, build and run the server in a throwaway environment — nothing is left behind:

uvx --from git+https://github.com/pkreissel/aleph-mcp aleph-mcp

From a local checkout, the same thing without the clone:

uvx --from /path/to/aleph-mcp aleph-mcp

This is what the Quickstart config runs, and it keeps no venv path that can go stale when you move the checkout.

Install as a tool

Persistent, on your PATH, still isolated:

uv tool install git+https://github.com/pkreissel/aleph-mcp

aleph-mcp is then on your PATH and speaks MCP over stdio — point a client at it by name rather than by path.

From a checkout

For development, or if you want the source on hand:

git clone https://github.com/pkreissel/aleph-mcp
cd aleph-mcp
uv venv
uv pip install -e .

The entry point is then .venv/bin/aleph-mcp.

Configure

Variable

Required

Purpose

ALEPH_HOST

no

Instance URL. Defaults to https://search.openaleph.org.

ALEPH_API_KEY

depends

API key for that instance. Also read from ALEPHCLIENT_API_KEY / MEMORIOUS_ALEPH_API_KEY by alephclient.

ALEPH_MCP_LOG_LEVEL

no

DEBUG, INFO, WARNING (default), ERROR. Logs go to stderr.

Whether you need a key depends on the instance. Most public ones reject unauthenticated requests to everything except /api/2/metadata, so without a key only aleph_get_schema_info works; get one from your profile page on that instance, under API Key. OpenAleph serves anonymous requests, so no key is needed there.

Claude Code

claude mcp add aleph \
  --env ALEPH_HOST=https://your-instance.org \
  --env ALEPH_API_KEY=your-key \
  -- /path/to/aleph-mcp/.venv/bin/aleph-mcp

Any client using mcpServers JSON

Against a checkout rather than uvx — see the Quickstart for the uvx form:

{
  "mcpServers": {
    "aleph": {
      "command": "/path/to/aleph-mcp/.venv/bin/aleph-mcp",
      "env": {
        "ALEPH_HOST": "https://your-instance.org",
        "ALEPH_API_KEY": "your-key"
      }
    }
  }
}

Hermes Agent

Hermes keeps its servers in ~/.hermes/config.yaml, under a top-level mcp_servers: key — YAML rather than JSON, and note the underscore:

mcp_servers:
  aleph:
    command: "uvx"
    args: ["--from", "git+https://github.com/pkreissel/aleph-mcp", "aleph-mcp"]
    env:
      ALEPH_HOST: "https://search.openaleph.org"
      ALEPH_API_KEY: ""

Then /reload-mcp in a session to pick it up without a restart. Hermes namespaces tools as mcp_<server>_<tool>, so with the server named aleph they arrive as mcp_aleph_aleph_search, mcp_aleph_aleph_get_entity and so on. Servers are scoped per Hermes profile — if the tools do not show up, check you are in the profile you added it to before assuming the install failed.

Several instances at once is just several entries with different ALEPH_HOST values and distinct server names.

Tools

Tool

Purpose

aleph_search

Search entities across every dataset you can read. Filter by schema, country and collection; request facets and highlighted snippets.

aleph_get_entity

Full record for one entity ID, every populated property.

aleph_expand_entity

Entities connected to this one, grouped by relationship type.

aleph_similar_entities

Candidate matches for the same real-world subject in other datasets.

aleph_list_collections

Discover datasets, filtered by name, category or country.

aleph_get_collection

Dataset metadata: publisher, source, coverage, update frequency, entity-type breakdown.

aleph_xref_results

Read cross-reference matches already computed for a dataset.

aleph_statistics

Instance size and shape, by entity type, category and country.

aleph_get_schema_info

followthemoney model reference: schemata and their properties.

aleph_fetch_document_text

Extracted text of a document entity, for quoting and verification.

How Aleph models data

Worth knowing, because it shapes how the tools chain together.

Everything is an entity with a schema (Person, Company, Document, Ownership, …) belonging to a collection (a dataset). Schemata inherit: Person extends LegalEntity extends Thing, and a search for LegalEntity returns companies and people alike.

Relationships are themselves entities. A person is not linked to a company by a field on the person; there is a separate Directorship entity pointing at both. That is why aleph_expand_entity exists — you cannot see the network by reading one record.

A typical investigation:

  1. aleph_search for the subject, narrowed by schema and countries.

  2. aleph_get_entity on the best hit for the full record.

  3. aleph_expand_entity to walk to officers, owners and addresses.

  4. aleph_similar_entities to find the same subject in other datasets.

  5. aleph_fetch_document_text to read the source document behind a claim.

Long documents store their text on child Page entities rather than the parent Document; if aleph_fetch_document_text finds no text, expand the document and fetch a page.

Results are search hits, not verified facts. Datasets are full of namesakes — confirm identity against birth dates, addresses or registration numbers before treating two records as the same person.

Output

Tools return compact text, not raw JSON. A page of Aleph results is tens of kilobytes of index bookkeeping; each entity is rendered down to its caption, schema, the featured properties for that schema, its source dataset, its entity ID and a URL that opens the record in the instance's web UI. IDs and URLs are always present, so every claim can be traced back to the source.

Instance notes

Instances differ in more than their data.

Bot filters. Some sit behind a proof-of-work challenge — search.openaleph.org uses Anubis, which 307-redirects unrecognised clients to a challenge page instead of returning JSON. It allowlists by User-Agent, and alephclient sends alephclient/<version>, which passes; plain curl or python-requests does not. So this server works as shipped, but anything that overrides the session User-Agent will start getting HTML back.

Reachable data. What a search returns is a function of the instance and of the key you gave it. aleph_list_collections and aleph_statistics are the quickest way to see what an instance actually holds before searching it.

Development

uv pip install -e ".[dev]"
.venv/bin/python -m pytest

The suite covers formatting, parameter construction, error mapping and an end-to-end stdio handshake against the real server process. It needs no network access and no API key: tests/metadata.json is a verbatim capture of a live instance's /api/2/metadata, so formatters run against the real followthemoney model.

Layout

src/aleph_mcp/
  server.py   tool definitions, argument schemas, error messages
  client.py   read-only Aleph access layered on alephclient
  format.py   API payloads -> compact text

alephclient supplies host/key configuration, the auth header and the session. It wraps only part of the API, so endpoints it does not cover (search with facets, expand, similar, xref, statistics, metadata) are issued as raw GETs over the same configured session.

Licence

MIT.

Available Tools

10 tools
aleph_expand_entityA
Read-only

List the entities connected to this one, grouped by relationship type (directorships, ownerships, addresses, family, document mentions). This is how you walk a network: relationships in Aleph are entities, so they do not appear as plain fields on the record itself.

Inputs: entity_id (required), limit, properties.

aleph_fetch_document_textA
Read-only

Read the extracted text of a document entity (PDF page, email, article) so you can quote or verify what it actually says. Pass the entity ID of a Document, Pages, Email or similar entity from a search result.

Inputs: entity_id (required), max_chars.

aleph_get_collectionA
Read-only

Full metadata for one dataset: publisher, source URL, coverage, update frequency and a breakdown of what entity types it contains. Use it to judge how far a source can be trusted and how current it is.

Inputs: collection_id (required).

aleph_get_entityA
Read-only

Fetch one entity by ID, with every populated property. Use after aleph_search to see the full record behind a hit.

Inputs: entity_id (required).

aleph_get_schema_infoA
Read-only

Reference for the followthemoney data model this instance uses. Call with no argument for the list of schemata; call with a name (Person, Company, Ownership, ...) for its properties and how it links to other schemata. Use it to pick the right schema filter or expand property.

Inputs: schema.

aleph_list_collectionsA
Read-only

List or search the datasets (collections) available to you — leaks, company registries, sanctions lists, court archives. Use it to discover what sources exist, then pass collection IDs to aleph_search to scope a query.

Inputs: limit, query, offset, category, +1 more.

aleph_similar_entitiesA
Read-only

Find entities that may be the same real-world person or company as this one, across other datasets. Use it to link a subject between a leak and a company registry. Results are ranked candidates, not confirmed matches — verify with birth dates, addresses or registration numbers.

Inputs: entity_id (required), limit.

aleph_statisticsA
Read-only

Size and shape of the Aleph instance: how many datasets and entities it holds, broken down by entity type, category and country. Use it to gauge coverage before concluding something is absent.

Inputs: no named parameters.

aleph_xref_resultsA
Read-only

Read the cross-reference results already computed for a dataset: entities in it that resemble entities elsewhere in Aleph, scored and ranked. Useful for finding overlaps between your own casefile and public registries. Read-only — this does not start a new cross-reference run.

Inputs: collection_id (required), limit, offset.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct Aleph operation: search, entity retrieval, network expansion, identity matching, collection metadata, statistics, schema lookup, xref result reading, and document text extraction. The closest pair (aleph_similar_entities and aleph_xref_results) is separated clearly by entity-level versus dataset-level scope.

    Naming Consistency3/5

    All tools share the aleph_ prefix and snake_case, but they do not follow one verb_noun convention: get_entity, list_collections, and fetch_document_text are verb-object, while statistics, xref_results, and similar_entities are noun/adjective phrases and search is a bare verb. Names are readable and predictable enough to navigate, but the pattern is mixed.

    Tool Count5/5

    Ten tools is well-scoped for an Aleph data exploration server: each tool covers a distinct read-side capability with no redundant utility tools or bloat.

    Completeness4/5

    The read-side investigation workflow is well covered: discover collections, search, inspect, expand, match, and read document text. However, the surface is explicitly read-only—there is no way to create or update casefile entities, write collections, or start a new cross-reference run—so it is not a full Aleph admin or casefile API.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables read-only search and exploration of the GenizahSearch research API, including manuscript search, page browsing, parallel finding, and multi-phrase queries, along with policy resources and research prompts.
      4
      Creative Commons Attribution Non Commercial Share Alike 4.0 International
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to query OpenCTI read-only during triage: resolving hashes, IPs, domains, URLs and emails against observables, and retrieving indicators, reports and relationships with scores, markings and external references. Enforces a TLP ceiling and input/output hardening so no data above the configured marking level is exposed.
      5
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to search public marketplace listings and projects for real-world assets, run unified searches, and fetch full public documents through read-only MCP tools.
      72 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only, keyless access to hosted job search through nine MCP tools for browsing postings, matching candidates, retrieving job details and discussion threads, resolving locations, listing companies, getting stats, and performing deep-research search/fetch.
      72 npm
      MIT