# MTRKR MCP Server

A read-only MCP server that connects AI agents to [MTRKR](https://mtrkr.xyz) wallet intelligence on [MegaETH](https://megaeth.com), an Ethereum L2.

The server registers **14** `mtrkr_*` tools for:

- `.mega` name resolution
- ERC-20 portfolios and USD pricing
- NFT holdings
- DeFi liquidity positions (AMM + concentrated-liquidity integrations)
- wallet activity summaries
- approval and operator scanning
- address inspection
- ERC-20 token risk scanning
- transaction decoding
- ETH/USD pricing
- wallet transaction analytics

Wallet transaction analytics are framed around the **MegaETH Terminal campaign** (season structure and incentives follow MTRKR’s published Terminal rules). They use **Terminal wave periods** loaded from MTRKR campaign config—for example, wave 1 **`2026-04-28`–`2026-05-05`**, **depending on the active MTRKR campaign config**; wave ids and date ranges can change when config updates. The tools support active-wave snapshots, recently finished wave reviews, multi-wallet comparison, and optional caller-supplied points for rough alignment checks.

These analytics are meant as a **companion you revisit each wave**: they summarize recent on-chain interactions, boosted-app coverage, outbound activity, and similar heuristics. They are **not official campaign or points scoring**.

**The server does not request private keys, sign transactions, or submit on-chain transactions.**

Wallet-scoped tools accept a MegaETH `0x` address or a `.mega` name (e.g. `mirage.mega`). Token risk scanning expects an **ERC-20 token contract** address. Transaction decoding expects a **32-byte transaction hash** (`0x` plus **64** hex characters). The ETH price tool takes **no inputs**; for questions like “value of N ETH in USD,” call `mtrkr_eth_price` and multiply by `N` client-side (or have the agent do it). See [Supported inputs](#supported-inputs).

## Requirements

- **Node.js 20+** (see `engines` in `package.json`)
- An **MCP-compatible host** (e.g. Cursor, Claude Desktop)
- **Network access** to MTRKR and upstream data sources used by the API
- **No API key** for the default public MTRKR origin; if you override [`MTRKR_API_URL`](#configuration), authentication requirements depend on that host

## Supported inputs

| Input kind | Tools |
| --- | --- |
| `.mega` name or wallet `0x` | Wallet portfolio, NFTs, activity summary / quick stats, LP positions, security scan, analytics GET/analyze, compare |
| `.mega` name or any MegaETH `0x` address | `mtrkr_resolve_name`, `mtrkr_inspect_address` |
| Token contract `0x` (not a wallet) | `mtrkr_token_scan` |
| Transaction hash, `0x` followed by **64** hex characters | `mtrkr_decode_transaction` |
| None | `mtrkr_eth_price` |

Names are resolved through MTRKR before calling the backing API where applicable.

## Quick start

Add the server to your MCP config, **restart the client**, and the tools should appear. No repo clone or local build is required if you use `npx`.

### Stable (recommended)

Use the **stable** tag npm exposes as `latest`:

**Cursor** — `.cursor/mcp.json` (project or global):

```json
{
  "mcpServers": {
    "mtrkr": {
      "command": "npx",
      "args": ["mtrkr-mcp-server@latest"]
    }
  }
}
```

**Claude Desktop** — `claude_desktop_config.json` (path varies by OS; see Anthropic docs):

```json
{
  "mcpServers": {
    "mtrkr": {
      "command": "npx",
      "args": ["mtrkr-mcp-server@latest"]
    }
  }
}
```

### Verify installation

After restarting the MCP host, try:

- "Resolve mirage.mega"
- "What is the current ETH price on MegaETH?"

### Beta / prerelease

User MCP config for the beta line:

```json
{
  "mcpServers": {
    "mtrkr": {
      "command": "npx",
      "args": ["mtrkr-mcp-server@beta"]
    }
  }
}
```

You can also pin an exact prerelease (example): `mtrkr-mcp-server@1.2.0-beta.0`. See [versions](https://www.npmjs.com/package/mtrkr-mcp-server?activeTab=versions) on npm.

## Configuration

Optional environment variable for the MCP **process** (set in the MCP config `env` block if your client supports it):

| Variable | Required | Description |
| --- | --- | --- |
| `MTRKR_API_URL` | No | **Origin** for the MTRKR HTTP API (scheme + host, **no trailing slash**). Requests append paths such as `/api/v1/...`. Default: `https://mtrkr.xyz`. |

No other environment variables are read by this package today.

Example MCP config fragment with `env`:

```json
{
  "mcpServers": {
    "mtrkr": {
      "command": "npx",
      "args": ["mtrkr-mcp-server@latest"],
      "env": {
        "MTRKR_API_URL": "https://mtrkr.xyz"
      }
    }
  }
}
```

## Tool index

| # | MCP tool | Summary | Main parameters |
| --- | --- | --- | --- |
| 1 | `mtrkr_resolve_name` | Resolve `.mega` ↔ primary `0x` | `input` (name or address) |
| 2 | `mtrkr_wallet_quick_stats` | Tx counts over a day range | `address`, `rangeDays` (1–365, default 30) |
| 3 | `mtrkr_security_scan` | Approvals & NFT operators | `address` |
| 4 | `mtrkr_wallet_tokens` | ERC-20 balances & USD | `address` |
| 5 | `mtrkr_wallet_nfts` | NFT holdings (capped list) | `address` |
| 6 | `mtrkr_lp_positions` | AMM-style LP positions | `address` |
| 7 | `mtrkr_prism_positions` | Concentrated-liquidity positions | `address` |
| 8 | `mtrkr_inspect_address` | EOA/contract inspection | `address` |
| 9 | `mtrkr_token_scan` | ERC-20 risk scan | `address` — **ERC-20 token contract** (not a wallet) |
| 10 | `mtrkr_decode_transaction` | Decode a transaction | `hash` |
| 11 | `mtrkr_eth_price` | ETH/USD | *(none)* |
| 12 | `mtrkr_companion_get` | One-wallet analytics snapshot | `address`; optional `whichWave`, `waveId`, or compatibility alias `wave` — [Terminal wave calendar](#wallet-transaction-analytics) |
| 13 | `mtrkr_companion_analyze` | Analytics + optional points alignment | `address`; optional `points`; optional `whichWave`, `waveId`, or compatibility alias `wave` |
| 14 | `mtrkr_companion_compare` | Compare up to 5 wallets | `addresses` (1–5); optional `pointsByAddress`; optional `whichWave`, `waveId`, or compatibility alias `wave` |

## Safety and limitations

Outputs are **informational** — risk scores, approvals, pricing, NFT/DeFi valuations, and decoded calldata depend on indexers, oracles, heuristics, and third-party feeds. **Gaps** are possible (non-standard contracts, delayed indexing, missing metadata, API outages).

**Not investment advice.** Treat token examples (honeypot, sell simulation) as **risk signals**, not buy/sell recommendations. Confirm critical findings with independent tools before acting.

## Tools

### Identity

**Name resolution** — **Tool:** `mtrkr_resolve_name`

Resolve a `.mega` name to a wallet address, or a wallet address to its primary `.mega` name. Uses on-chain name resolution via MTRKR.

**Try asking:**
- "What address is mirage.mega?"
- "Does 0x1234...abcd have a .mega name?"
- "Resolve mirage.mega"

### Wallet portfolio

**Token balances and pricing** — **Tool:** `mtrkr_wallet_tokens`

Discover ERC-20 tokens held by a wallet with balances, USD pricing, and metadata. Uses hybrid discovery (token-list multicall plus transfer-log style scanning) so **many** tokens appear even when they are not on the default list; coverage still depends on RPC and indexer behavior.

**Example shape** (illustrative; fields may vary with API versions):

```json
{
  "tokens": [
    {
      "address": "0x…",
      "symbol": "USDM",
      "name": "…",
      "balance": 100.0,
      "balanceUsd": 100.0,
      "priceUsd": 1.0
    }
  ],
  "totalUsd": 1234.56
}
```

**Try asking:**
- "What tokens does mirage.mega hold?"
- "Show me the token portfolio for 0x1234...abcd"
- "What's the total USD value of 0xdead...beef's tokens?"
- "Does this wallet hold any USDM?"

**NFT holdings** — **Tool:** `mtrkr_wallet_nfts`

NFTs on MegaETH (ERC-721, ERC-1155, ERC-404). Data is merged from chain indexers, marketplace feeds, badges, and enumeration. Returns up to **25** items, ordered using available floor-price metadata. **Floor prices and attributes** depend on marketplace/indexer availability and may be stale or absent.

**Try asking:**
- "What NFTs does mirage.mega own?"
- "Show me the NFT collection for 0x1234...abcd"
- "Does this wallet hold any Fluffle NFTs?"
- "What's the floor price of the NFTs in 0xdead...beef?"

**Activity summary (quick stats)** — **Tool:** `mtrkr_wallet_quick_stats`

Transaction counts (in/out/total) over a configurable range (1–365 days).

**Try asking:**
- "How active is 0x1234...abcd over the last 90 days?"
- "How many transactions has mirage.mega sent this week?"
- "Compare inbound vs outbound tx count for 0xdead...beef in the last 30 days"

### DeFi positions

**Primary AMM liquidity** — **Tool:** `mtrkr_lp_positions`

Active LP positions for the supported AMM integration: pairs, ticks, liquidity, unclaimed fees, USD estimates. Closed zero-value positions are filtered out. Uses indexer-backed data with RPC fallback where applicable.

**Try asking:**
- "What LP positions does mirage.mega have in supported pools?"
- "How much liquidity does this wallet provide in integrated AMM positions?"
- "What fees has 0xdead...beef earned from LP positions?"

**Concentrated liquidity** — **Tool:** `mtrkr_prism_positions`

Concentrated-liquidity positions (NFT position-manager style). On-chain position readout with pairs, ticks, in-range status, liquidity, USD estimates.

**Try asking:**
- "What concentrated-liquidity positions does mirage.mega have?"
- "Show me CL positions for 0x1234...abcd"
- "Are any of 0xdead...beef's positions out of range?"

### Security & analysis

**Approval and operator scan** — **Tool:** `mtrkr_security_scan`

Open ERC-20 allowances and NFT operator permissions with coarse risk labels and spender context. Uses historical indexing **subject to** indexer completeness, reorgs, non-standard patterns, and API availability — treat as a strong signal, not a mathematical guarantee.

**Try asking:**
- "Does mirage.mega have risky approvals?"
- "List all infinite approvals for 0x1234...abcd"
- "Are there any critical-risk token approvals on 0xdead...beef?"
- "How many unknown spenders does this wallet have approved?"

**Address inspection** — **Tool:** `mtrkr_inspect_address`

Inspect any MegaETH address: EOA vs contract, balance, labels, proxy hints, deployer/owner where available, verification, token interfaces, clone heuristics, and a qualitative risk summary.

**Try asking:**
- "Is 0x1234...abcd a wallet or a contract?"
- "Inspect 0xdead...beef — is it a proxy?"
- "Who deployed contract 0x5B42...d997?"
- "Is 0xabcd...1234 source-verified on the network explorer?"
- "What token standard does 0x021e...782B implement?"
- "Is this contract a fake clone?"

**Token risk report** — **Tool:** `mtrkr_token_scan`

Multi-domain ERC-20 risk heuristics (control, exit, liquidity, economics, integrity): numeric score, findings, sell-path simulation, admin proxies, concentration, curation flags, etc. **Not exhaustive** — unknown exploit classes and data gaps always remain.

**Try asking:**
- "Analyze contract risk for token 0x021e...782B"
- "Can I sell 0xabcd...1234? Check for honeypot"
- "What are the risk factors for 0xdead...beef?"
- "Who are the top holders of 0x021e...782B?"
- "Does 0xabcd...1234 have admin mint or pause powers?"
- "Is 0xdead...beef on the MegaETH curated token list?"

### Wallet transaction analytics

#### Period parameters: Terminal campaign waves

Prefer **`whichWave`** for normal usage:

- **`whichWave: "current"`** — active Terminal wave
- **`whichWave: "last_completed"`** — most recently closed Terminal wave

Use **`waveId`** when you need a **specific** historical wave (`1` … `n` from campaign config). **`wave`** is kept as a **compatibility alias** (GET: string tokens like `current`, `last_completed`, or digit strings that map to `waveId`; analyze/compare POST bodies may also forward string or number `wave`).

| Argument | Type | Allowed values | Used by |
| --- | --- | --- | --- |
| `whichWave` | optional enum | `current`, `last_completed` | All three analytics tools |
| `waveId` | optional int | Terminal wave id from campaign config | All three |
| `wave` | optional string or number | Compatibility alias (see above) | All three |

**Tools:** `mtrkr_companion_get`, `mtrkr_companion_analyze`, `mtrkr_companion_compare`.

**Terms**

- **Decoded ledger:** outbound transactions in the **selected Terminal wave** (`startDate`–`endDate` from campaign config), with method/value context from MTRKR’s decoder where available.  
- **Tracked apps:** application labels when a call targets an address known to MTRKR’s app directory.  
- **Points alignment:** when you pass points, the API may echo heuristic alignment — **not** an official points calculation.

**Read analytics snapshot** — **Tool:** `mtrkr_companion_get`

**Try asking:**
- "For **mirage.mega** **last completed Terminal wave**, summarize **every outbound tx** from the **decoded ledger** (swaps, bridges, others) and which map to **tracked apps**."
- "Wallet transaction analytics snapshot for 0x… for **period id** 3"

**Analyze with optional points** — **Tool:** `mtrkr_companion_analyze`

Returns the same family of analytics payload as the snapshot tool, plus optional **points-alignment** output when you supply `points`.

**Try asking:**
- "I logged about **1200 points** in the **last completed Terminal wave** — analyze wallet 0x… with those numbers and see if on-chain activity is in the same ballpark"

**Compare wallets** — **Tool:** `mtrkr_companion_compare`

**Try asking:**
- "Compare mirage.mega, 0xAAA…, and 0xBBB… for the **current Terminal wave** — who has broader **tracked-app** coverage and more outbound volume?"

### Utility

**Transaction decode** — **Tool:** `mtrkr_decode_transaction`

Human-readable calldata, transfers, events, and contract context when **transaction data, receipts, and decoder inputs** are available from upstream services.

**Try asking:**
- "What did transaction 0xf9b5...3e2a do?"
- "Decode 0xabcd...1234 — was it a swap?"
- "Show me the token transfers in tx 0xdead...beef"
- "What method was called in transaction 0x9876...5432?"

**Spot ETH price** — **Tool:** `mtrkr_eth_price`

ETH/USD from an on-chain oracle when available, otherwise a market reference; response includes **source** metadata when the API provides it. The tool returns a **single ETH price**, not an amount conversion — agents or clients should multiply by the desired ETH quantity after the call.

**Try asking:**
- "What's the current ETH price on MegaETH?"
- "ETH price?"
- "How much is 5 ETH worth in USD right now?"

## Troubleshooting

- **Tools do not appear:** Restart the MCP host after editing config; validate JSON; run `node --version` (20+); try `npx mtrkr-mcp-server@latest` in a terminal to confirm the package resolves.
- **Stale or unexpected version:** Pin a semver: `"args": ["mtrkr-mcp-server@1.1.1"]` or check dist-tags: `npm view mtrkr-mcp-server dist-tags`.
- **Rate limiting:** MTRKR may return **429**; wait briefly and retry (analytics compare is heavier).
- **`.mega` fails to resolve:** Confirm the name exists and MTRKR resolution succeeds for that label.

## Changelog (high level)

- **1.2.x (beta → stable):** Wallet transaction analytics
- **1.1.x:** Earlier stable line on npm; see [package versions](https://www.npmjs.com/package/mtrkr-mcp-server?activeTab=versions).

## License

MIT — see `package.json`.