Model Context Protocol (MCP) Server: io.github.ptrinh/freeport-nostr

This MCP server enables searching Freeport Nostr events using parameters for kind, tag, and a geohash radius. It targets multiple event categories including rides, services, and reputation, and exposes multiple tools (6 total) to support those queries.

🛠️ Key Features

Search Freeport Nostr events
Filter by kind
Filter by tag
Filter by geohash radius
Event categories referenced: rides, services, reputation
Tool availability count: 6

🚀 Use Cases

Find Nostr events for a specific kind
Narrow results using event tags
Locate events within a geographic area via geohash radius
Look up rides, services, or reputation-related events

⚡ Developer Benefits

Structured event search across multiple Freeport Nostr domains (rides, services, reputation)
Parameterized queries (kind, tag, geohash radius)
Multiple tools (6) to integrate into developer workflows

⚠️ Limitations

Only event search capabilities are described (no other functions provided in the provided data)

{ "type": "object", "properties": { "side": { "type": "string", "enum": [ "offer", "request", "any" ], "default": "any", "description": "offer = drivers/providers/sellers; request = riders/buyers; any = both" }, "topics": { "type": "array", "items": { "type": "string" }, "description": "Topic `t` tags to require (category/subcategory/area keys, e.g. \"vn_hanoi\", \"ridesharing\")." }, "near": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "radiusKm": { "type": "number", "exclusiveMinimum": 0, "maximum": 20000, "default": 100 } }, "required": [ "lat", "lon" ], "additionalProperties": false, "description": "Filter & sort by distance from this point." }, "relaySideGeohash": { "type": "boolean", "default": false, "description": "Also narrow at the relay via a #g cover of the radius. Only effective if posts carry geohash-prefix tags; off by default." }, "since": { "type": "integer", "description": "Only events created at/after this unix-seconds time." }, "until": { "type": "integer", "description": "Only events created at/before this unix-seconds time." }, "includeExpired": { "type": "boolean", "default": false }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 }, "relays": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }

{ "type": "object", "properties": { "pubkey": { "type": "string", "description": "Subject pubkey (hex) to look up reputation for." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 }, "relays": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays." } }, "required": [ "pubkey" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }

{ "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "relays": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays." } }, "required": [ "ids" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }

{ "type": "object", "properties": { "pubkeys": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "Hex pubkeys to fetch profiles for." }, "recentNotes": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0, "description": "If >0, also fetch up to this many recent text notes (kind 1) per pubkey." }, "relays": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays." } }, "required": [ "pubkeys" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }

{ "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "integer" } }, "authors": { "type": "array", "items": { "type": "string" } }, "ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Tag filters, e.g. {\"t\":[\"vn_hanoi\"],\"g\":[\"w3gv\"]}. Keys are single tag letters." }, "since": { "type": "integer" }, "until": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "relays": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }

{ "type": "object", "properties": { "secretKey": { "type": "string", "description": "nsec or 64-hex private key. Used transiently to sign; never stored. Omit if passing a pre-signed `event`." }, "side": { "type": "string", "enum": [ "offer", "request" ], "description": "offer = provider/seller/driver; request = buyer/rider." }, "market": { "type": "string", "description": "Market key, e.g. \"rideshare\" or \"service\"." }, "schema": { "type": "string", "description": "Payload schema, e.g. \"rideshare/1\" or \"service/1\"." }, "title": { "type": "string", "maxLength": 200 }, "payload": { "type": "object", "additionalProperties": {}, "description": "Intent payload (from/to/location, payment, etc.) per the freeport://protocol resource." }, "expiresInMinutes": { "type": "integer", "minimum": 5, "maximum": 43200, "description": "How long the post stays live (default 720). Max 30 days." }, "window": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "required": [ "start", "end" ], "additionalProperties": false }, "geohashes": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "description": "Geohashes for location-scoped discovery. Each is expanded into all its prefixes (precision 1-6) so radius searches at any precision match." }, "topics": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "description": "Topic `t` tags (area/category), e.g. [\"vn_hanoi\",\"vn_hanoi_ridesharing\"]." }, "d": { "type": "string", "description": "Stable id to republish/replace an existing post; defaults to random." }, "event": { "description": "A complete, signed Nostr event (kind 32101/32102). Use instead of secretKey to keep keys off the server." }, "relays": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }

Freeport

Decentralized P2P marketplace over Nostr. Users broadcast trade intents into topic-scoped markets; personal agents discover counterpart intents and negotiate automatically. Humans confirm final deals. No central operator, no matching server — relays are dumb pub/sub, all logic is client-side.

App: https://freeport.network (web/PWA) · iOS · Android · Desktop — Mac/Windows/Linux · Offline HTML

Whitepaper: PDF

Self-host: packages/freeport-self-hosted (docker compose up -d), or any desktop install can host the app for your network with freeport --serve.

Developers: CONTRIBUTING.md — repo layout, stack decisions, quick start, CLI.

Why Freeport exists

It's a research project. How far can pure P2P infrastructure go? Buyers, sellers, riders, drivers meet over Nostr, settle in Lightning or cash. Nothing in between needs permission to exist.

It's a thesis. A P2P marketplace with a reputation system works. When people own their reputation, the market self-regulates.

It's a check and balance. A zero-fee exit that answers to no one puts a ceiling on how greedy the big platforms can get.

It's fun. An open protocol, Claude Code as a pair programmer, no investor deck.

Nobody profits — including me. No operator, no cut. A protocol, not a platform. Run it or fork it.

No one will protect you here — that's the point, and the price. No support line, no refunds, no central authority. Your judgment comes first, backed by opt-in safeguards no operator runs: a reputation system (karma, co-signed receipts, web-of-trust), escrow arbitration (examples/arbitrator), ID verification (examples/id-verification), and insurance (examples/insurance-store) priced from reputation. You choose how much of the safety net to use.

What works today

Everywhere: iOS + Android app stores, web/PWA, desktop installers for macOS/Windows/Linux with self-update — plus a single-file offline copy: the whole app in one HTML file that runs from file://, no install, no server.

Wallet (experimental): built-in self-custodial Bitcoin Lightning + stablecoin (USDT/USDB) wallet (Breez SDK/Spark). Keys derive from your Nostr key — one backup covers identity and funds. Lightning address (you@freeport.network), on-chain, QR scan, local-currency balances, and one-tap Pay / Pay QR on confirmed deals. Bring your own wallet over NWC instead if you prefer. Spark is a young trust-minimized L2 — treat it as a spending wallet.

Reputation: peer-rated karma, co-signed deal receipts, proven-deal counts, web-of-trust weighting. Sybil resistance stays open — treat zero-history identities with caution.

Chat: invite-based 1:1 encrypted chat beyond deals — QR/link invites, replies, emoji reactions, disappearing messages, delivery/read receipts, voice messages, location sharing, in-chat search and Lightning payments. Between updated clients it upgrades to NIP-17 gift wrap, so relays can't even see who talks to whom.

Calls (experimental): peer-to-peer audio/video calls in chat (WebRTC, end-to-end encrypted, signaling over encrypted DMs — no call server), with screen sharing on web. Optional TURN fallback.

Zaps & Shops: NIP-57 zap tipping on posts (verifiable receipts), and NIP-15 storefronts — durable seller listings with a conversational "chat with seller" checkout.

Escrow without a custodian: HODL-invoice conditional payments on confirmed deals — the buyer holds the preimage, the seller can only settle on release, unreleased funds auto-refund. The Lightning protocol enforces the lock; nobody ever holds the money in between.

Mini-apps (experimental): third-party web apps run inside Freeport with your portable identity (NIP-07) and wallet (WebLN + Spark/stablecoin) — sandboxed behind a permission firewall where every sensitive action needs your approval (architecture & threat model). A dedicated Apps tab hosts the launcher — a home-screen-style grid (add any app by URL or QR, drag to rearrange), with the wallet as its first tile; your apps and their grants travel with the account backup. One <script> tag makes a page work on web too. Mini-app examples:

examples/esim-store — eSIM shop with Spark/stablecoin checkout, live at apps.freeport.network/esim-store
examples/insurance-store — travel insurance quotes underwritten from npub-derived reputation, with a downloadable PDF certificate, live at apps.freeport.network/insurance-store
examples/id-verification — a paid identity / licence verification service: submit documents, book a video call, and get a shareable verification link for your profile, live at apps.freeport.network/id-verification
examples/arbitrator — decentralized dispute arbitration: an escrow with the arbitrator as a conditional key, encrypted evidence (NIP-44), and a fee only charged when a dispute is actually raised — the arbitrator's npub karma is their license, live at apps.freeport.network/arbitrator

On-device AI (experimental): describe what you need in any language and it drafts your post; incoming chat messages auto-translate. Runs entirely on your device (Apple Intelligence / Android ML Kit + Gemini Nano / Chrome built-in AI) — your words never leave it.

Notifications & Telegram: content-blind push, plus a Telegram bridge — market feeds in groups, one-tap broadcast of organic posts, personal pings.

56 languages, full RTL, in-chat translation.

Install

Tools (6)

nostr_search_intentsnostr_search_reputationnostr_get_eventnostr_profilenostr_query_rawfreeport_create_post

Configuration

Environment variables

FREEPORT_RELAYS

Comma-separated relay websocket URLs. Defaults to the Freeport public relay set.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "freeport-nostr": {
      "command": "npx",
      "args": [
        "-y",
        "freeport-nostr-mcp@0.5.0"
      ],
      "env": {
        "FREEPORT_RELAYS": "<YOUR_FREEPORT_RELAYS>"
      }
    }
  }
}

io.github.ptrinh/freeport-nostr

Model Context Protocol (MCP) Server: io.github.ptrinh/freeport-nostr

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

nostr_search_intents

nostr_search_reputation

nostr_get_event

nostr_profile

nostr_query_raw

freeport_create_post

Freeport

Demo (2 minutes)

Why Freeport exists

What works today

Non-goals (v1)

Donate

License & forking

Install

Configuration

Related servers

side	string	optional	offer = drivers/providers/sellers; request = riders/buyers; any = both
topics	array	optional	Topic `t` tags to require (category/subcategory/area keys, e.g. "vn_hanoi", "ridesharing").
near	object	optional	Filter & sort by distance from this point.
relaySideGeohash	boolean	optional	Also narrow at the relay via a #g cover of the radius. Only effective if posts carry geohash-prefix tags; off by default.
since	integer	optional	Only events created at/after this unix-seconds time.
until	integer	optional	Only events created at/before this unix-seconds time.
includeExpired	boolean	optional
limit	integer	optional
relays	array	optional	Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

pubkey	string	required	Subject pubkey (hex) to look up reputation for.
limit	integer	optional
relays	array	optional	Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

pubkeys	array	required	Hex pubkeys to fetch profiles for.
recentNotes	integer	optional	If >0, also fetch up to this many recent text notes (kind 1) per pubkey.
relays	array	optional	Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

kinds	array	optional
authors	array	optional
ids	array	optional
tags	object	optional	Tag filters, e.g. {"t":["vn_hanoi"],"g":["w3gv"]}. Keys are single tag letters.
since	integer	optional
until	integer	optional
limit	integer	optional
relays	array	optional	Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

secretKey	string	optional	nsec or 64-hex private key. Used transiently to sign; never stored. Omit if passing a pre-signed `event`.
side	string	optional	offer = provider/seller/driver; request = buyer/rider.
market	string	optional	Market key, e.g. "rideshare" or "service".
schema	string	optional	Payload schema, e.g. "rideshare/1" or "service/1".
title	string	optional
payload	object	optional	Intent payload (from/to/location, payment, etc.) per the freeport://protocol resource.
expiresInMinutes	integer	optional	How long the post stays live (default 720). Max 30 days.
window	object	optional
geohashes	array	optional	Geohashes for location-scoped discovery. Each is expanded into all its prefixes (precision 1-6) so radius searches at any precision match.
topics	array	optional	Topic `t` tags (area/category), e.g. ["vn_hanoi","vn_hanoi_ridesharing"].
d	string	optional	Stable id to republish/replace an existing post; defaults to random.
event	any	optional	A complete, signed Nostr event (kind 32101/32102). Use instead of secretKey to keep keys off the server.
relays	array	optional