aleph-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., "@aleph-mcp Search for entities connected to the Panama Papers"
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.
aleph-mcp
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-mcpThen 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-mcpFrom a local checkout, the same thing without the clone:
uvx --from /path/to/aleph-mcp aleph-mcpThis 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-mcpaleph-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 |
| no | Instance URL. Defaults to |
| depends | API key for that instance. Also read from |
| no |
|
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-mcpAny 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 |
| Search entities across every dataset you can read. Filter by schema, country and collection; request facets and highlighted snippets. |
| Full record for one entity ID, every populated property. |
| Entities connected to this one, grouped by relationship type. |
| Candidate matches for the same real-world subject in other datasets. |
| Discover datasets, filtered by name, category or country. |
| Dataset metadata: publisher, source, coverage, update frequency, entity-type breakdown. |
| Read cross-reference matches already computed for a dataset. |
| Instance size and shape, by entity type, category and country. |
| followthemoney model reference: schemata and their properties. |
| 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:
aleph_searchfor the subject, narrowed byschemaandcountries.aleph_get_entityon the best hit for the full record.aleph_expand_entityto walk to officers, owners and addresses.aleph_similar_entitiesto find the same subject in other datasets.aleph_fetch_document_textto 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 pytestThe 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 textalephclient 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 toolsaleph_expand_entityARead-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_textARead-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_collectionARead-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_entityARead-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_infoARead-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_collectionsARead-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_searchARead-only
Search entities (people, companies, documents, ...) across every Aleph dataset you can read. This is the main entry point. Returns compact summaries with entity IDs to pass to the other tools. Request facets to see which countries or datasets the matches cluster in.
Inputs: query (required), limit, facets, offset, +4 more.
aleph_similar_entitiesARead-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_statisticsARead-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_resultsARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Free, read-only public-source threat intel over MCP. No account or API key.
Read-only access to InfluSense influencer discovery, ratings, watchlists, and reports via MCP.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables 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.4Creative Commons Attribution Non Commercial Share Alike 4.0 International
- AlicenseAqualityBmaintenanceEnables 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.5Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT