Performs blockchain AML screening for crypto addresses to identify sanctions, risk scores, fund tracing, and counterparties.
Also known as publicaml/mcp-server, @publicaml/mcp-server
- Stars
- 0
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Nov 6, 2026
- License
- MIT
What is PublicAML MCP?
PublicAML performs blockchain AML screening for crypto addresses to identify sanctions, risk scores, fund tracing, and counterparties. It exposes 3 tools, such as screen_address, trace_funds, list_counterparties.
Summary generated from the project's README
About PublicAML MCP server
Performing blockchain AML screening for crypto addresses from inside Claude Desktop, Cursor, or other MCP clients is what this server enables. It allows users to investigate Bitcoin, Ethereum, BSC, Tron, and Solana addresses using plain language to identify sanctions, risk scores, and fund movements. The tool provides details on issuer freezes, transaction graph risks, and the specific roles an address plays in various incidents, such as being a perpetrator or a victim.
Developers can use the screen_address tool to find risk levels and entity classifications like exchanges or mixers. For deeper investigations, the trace_funds tool follows incoming or outgoing flows, while list_counterparties helps classify entities or check lists of suspect addresses. The server works without an account, but providing a PUBLICAML_API_KEY increases rate limits and enables outgoing fund tracing.
This server is designed for security researchers and investigators who need to verify wallet identities and transaction histories. It distinguishes between confirmed community attributions and unconfirmed victim reports to ensure users understand the certainty of the data provided.
What you can do with it
- 1Screening a suspicious walletCheck a specific crypto address for sanctions, risk scores, and its role in known incidents.
- 2Tracing fund movementsFollow the path of money backwards to see who funded a wallet or forwards to see where funds left the chain.
- 3Identifying counterparty typesDetermine if a wallet has interacted with specific types of entities like exchanges, mixers, or casinos.
- 4Verifying suspect address listsTest a group of suspicious addresses against a specific wallet to see if there is any connection.
Written from the project's README. Every use case is checked against a quote from it.
How to install PublicAML MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall PublicAML MCP in Claude Code
$ claude mcp add --env 'PUBLICAML_API_KEY=<YOUR_PUBLICAML_API_KEY>' mcp-server -- npx -y @publicaml/mcp-serverInstall PublicAML MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@publicaml/mcp-server"
],
"env": {
"PUBLICAML_API_KEY": "<YOUR_PUBLICAML_API_KEY>"
}
}
}
}Install PublicAML MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@publicaml/mcp-server"
],
"env": {
"PUBLICAML_API_KEY": "<YOUR_PUBLICAML_API_KEY>"
}
}
}
}Install PublicAML MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@publicaml/mcp-server"],"env":{"PUBLICAML_API_KEY":"<YOUR_PUBLICAML_API_KEY>"}}'Install PublicAML MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@publicaml/mcp-server"
],
"env": {
"PUBLICAML_API_KEY": "<YOUR_PUBLICAML_API_KEY>"
}
}
}
}Install PublicAML MCP in Codex
$ codex mcp add mcp-server --env 'PUBLICAML_API_KEY=<YOUR_PUBLICAML_API_KEY>' -- npx -y @publicaml/mcp-serverInstall PublicAML MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@publicaml/mcp-server"] [mcp_servers.mcp-server.env] PUBLICAML_API_KEY = "<YOUR_PUBLICAML_API_KEY>"
Install PublicAML MCP in Gemini CLI
$ gemini mcp add -s user -e 'PUBLICAML_API_KEY=<YOUR_PUBLICAML_API_KEY>' mcp-server npx -- -y @publicaml/mcp-serverInstall PublicAML MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@publicaml/mcp-server"
],
"env": {
"PUBLICAML_API_KEY": "<YOUR_PUBLICAML_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @publicaml/mcp-server 0.1.1 in an isolated container with no network and no keys. It answered and listed 3 tools.
PublicAML MCP tools 3
Read from the server with tools/listscreen_addressAML screening for one blockchain address: risk level and score, sanctions, issuer freezes (Tether/Circle), what the address is (exchange, mixer, gambling, bridge, personal wallet) and where its risk comes from. Chains: bitcoin, ethereum, bsc, tron. Read the answer this way: `sanctioned: true` is a blocking fact on its own, independent of the score. The score is a risk reading 0-100, never a share of the funds. An address absent from the data is reported as NOT FOUND and must not be presented as clean. Chain is part of the address's identity, not a hint: the same 0x address is a different wallet on ethereum, bsc and tron. Pass `chain` when you know it; if you omit it, every chain the format allows is screened and each result is labelled with its chain.
trace_fundsFollows the money one direction at a time. `incoming` walks funding backwards: who paid this wallet. The trail stops at labelled entities (it reports the exchange rather than walking into its other customers) and at unlabelled addresses whose degree makes them a service. `outgoing` follows the largest outgoing flows forward to where the money left the anonymous part of the chain (exchange, OTC, mixer) and what is still sitting in unlabelled dead ends. Outgoing tracing needs an API key. This is a lead-generating tool, not exhaustive accounting: the walk is bounded by wall clock, so a partial answer is returned rather than a timeout, and 'nothing found' can mean 'the budget ran out'. The answer says which one it was; report that honestly.
list_counterpartiesWho a wallet dealt with and for how much, in one of three modes: `classify` — enumerate the counterparties and say what each one IS: a person, a venue (exchange/service), a hub, a deposit address, a contract or a mint/burn pseudo-address. This is the mode for 'which ordinary people funded this wallet'. An unlabelled counterparty is NOT thereby a person; that is what this mode's degree probe decides. `category` — did this wallet touch any exchange / mixer / gambling site / bridge at all. `check` — you already have suspect addresses and want to know whether this wallet dealt with them, and for how much. Addresses with no recorded interaction are simply absent from the answer. The list is ranked and capped, so a `partial` answer is a floor, not the complete set, and a degree figure is a lower bound measured in a window.
Configuration
PUBLICAML_API_KEYSecretOptional. Without it the server works anonymously under an IP rate limit and outgoing tracing is unavailable.
PUBLICAML_API_BASEOptional. Override the API base URL. Default https://intelapi.publicaml.org
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablepublicaml/mcp-server is public and reachablegithub.com/publicaml/mcp-server ↗Pass
- Package names this repository as its source@publicaml/mcp-server names publicaml/mcp-server as sourcenpmjs.com/package/@publicaml/mcp-server ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/publicaml/mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @publicaml/mcp-serverPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPublicAML MCP server
Blockchain AML screening inside Claude Desktop, Cursor, or any other MCP client. Ask about an address in plain language and the assistant checks it against PublicAML: sanctions, issuer freezes, risk propagated through the transaction graph, who funded the wallet and who it dealt with.
Chains: bitcoin, ethereum, bsc, tron. screen_address also covers solana,
where the score uses direct evidence only (no risk is propagated), so a Solana
address without evidence of its own comes back NOT SCORED rather than 0.
Works without an account. An API key only lifts the rate limit and unlocks forward tracing.
Install
Claude Desktop, claude_desktop_config.json:
{
"mcpServers": {
"publicaml": {
"command": "npx",
"args": ["-y", "@publicaml/mcp-server"]
}
}
}
With an API key:
{
"mcpServers": {
"publicaml": {
"command": "npx",
"args": ["-y", "@publicaml/mcp-server"],
"env": { "PUBLICAML_API_KEY": "your-key" }
}
}
}
Cursor uses the same block in .cursor/mcp.json. Claude Code:
claude mcp add publicaml -- npx -y @publicaml/mcp-server
Tools
screen_address
Risk level and score, sanctions, Tether/Circle freezes, what the address is
(exchange, mixer, gambling, bridge, personal wallet), where its risk comes
from, and the incidents it is named in with its role in each (perpetrator,
intermediary, recipient, victim, mentioned). Reads POST /v2/enrich.
Victims' reports are kept apart from attribution. A pending claim from a
victim report ("this is a KuCoin hot wallet") is printed on its own line,
Reported by a victim (not confirmed, does not affect the score): …, with a
link to the report, and never as the address's identity. Community incidents
that nobody has confirmed are marked community report, not confirmed. A
claim a PublicAML curator has confirmed (community:confirmed) is an ordinary
attribution.
The answer ends with a link to the public victim-report form with the address
prefilled (https://publicaml.org/victim-reports/?chain=…&address=…), so the
assistant can offer it to a user who lost funds. The server itself never files
reports or writes labels.
chain is optional. Omit it and every chain the address format allows is
screened, each result labelled with its chain: the same 0x… string is a
different wallet on ethereum, bsc and tron, so it is never guessed silently.
trace_funds
direction: "incoming" walks the funding backwards to answer "who paid this
wallet", stopping at labelled entities rather than walking into an exchange's
other customers. direction: "outgoing" follows the largest outgoing flows to
where the money left the chain's anonymous part. Outgoing needs an API key.
The walk is bounded by wall clock, so an incomplete answer is returned rather than a timeout, and the answer says which one it is.
list_counterparties
Three questions, one tool. classify enumerates counterparties and says what
each one is (person, venue, hub, deposit address, contract, mint/burn).
category answers "did this wallet touch any exchange / mixer / casino".
check tests a list of suspect addresses against the wallet.
Reading the answers
- SANCTIONED is a blocking fact on its own, whatever the score says.
- NOT SCORED (for example a Solana address with no evidence of its own) is not a score of 0 and not a clean result.
- The score is a risk reading 0-100, never a share of the funds, and its parts combine by MAX, so the breakdown does not add up to the total.
- An address absent from the data comes back as NOT FOUND. That is unknown, not clean.
- An unconfirmed victim report or community incident is one person's report, not PublicAML's finding.
- Lists are ranked and capped. A
PARTIALanswer is a floor, not a census. - USD figures cover priced tokens only and can be inflated by low-liquidity tokens. Treat them as an order of magnitude.
This is evidence for a human decision, not the decision itself.
Configuration
| Variable | Default | Meaning |
|---|---|---|
PUBLICAML_API_KEY |
none | Lifts the anonymous rate limit, unlocks outgoing tracing. |
PUBLICAML_API_BASE |
https://intelapi.publicaml.org |
API base URL. |
PUBLICAML_TIMEOUT_MS |
60000 |
Per-request timeout. |
PUBLICAML_TRACE_CONTINUES |
2 |
How many times an incomplete backward walk is resumed automatically. |
One-click desktop install
The same server is also distributed as an MCPB bundle, which Claude Desktop installs with a double click and no JSON editing. Build it with:
npm run build:mcpb
The bundle lands in dist/. Version, description, licence and the tool list are
read from package.json and from the server's own tool definitions, so the
bundle cannot drift from the npm release.
Development
npm install
npm test # unit tests, no network
node scripts/live.mjs # end-to-end against the live API
Releasing
- Bump
versioninpackage.jsonand bothversionfields inserver.json(the server reads its own version frompackage.json). npm test, thennode scripts/live.mjs.npm publish --access public(npm account of the@publicamlscope).mcp-publisher login githubandmcp-publisher publish— updates the MCP Registry entryio.github.publicaml/mcp-serverfromserver.json.npm run build:mcpband attachdist/publicaml-mcp-server-<version>.mcpbto the GitHub release; tagv<version>.
MIT licensed. API docs: https://publicaml.org/api
PublicAML MCP questions
How do I add PublicAML MCP to Claude Code?
Run claude mcp add --env 'PUBLICAML_API_KEY=<YOUR_PUBLICAML_API_KEY>' mcp-server -- npx -y @publicaml/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add PublicAML MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does PublicAML MCP provide?
It exposes 3 tools, including screen_address, trace_funds, list_counterparties.
Does this server require an account to use?
No, it works without an account, but using an API key increases rate limits and enables outgoing fund tracing.
Which blockchains are supported?
The server supports Bitcoin, Ethereum, BSC, and Tron, and also covers Solana with direct evidence scoring.
What does a 'NOT SCORED' result mean?
A 'NOT SCORED' result is not a score of 0; it occurs when there is no direct evidence, such as with certain Solana addresses.