Gittr

gittr-mcp

Let your AI agent (or app) use gittr — Nostr git hosting — like a developer would — create repos, push code, open and merge pull requests, manage issues, and work with Lightning bounties — using your Nostr identity, not a GitHub login.

Works with Cursor, Claude Desktop, VS Code / Copilot MCP, Windsurf, OpenClaw, or any host that speaks the Model Context Protocol over stdio.

Docs hub: gittr-docu — product map and how this MCP sits next to the website.

This repo’s Page: root index.html. After Push Manifest, save site name gittr-mcp.

Why use this?

End result: one MCP server connects your agent to decentralized git on Nostr — same account as on gittr.space (nsec / keys file), no separate vendor account for the agent.

Hosting note: The website Create/Import flow stays browser-local until announce/Push. MCP createRepo / mirrorRepo / pushToBridge write the git the same way the website does. The clone addresses are the servers saved under Settings → Relays (yours first), then the public copies. Soft-delete POSTs the tombstone to the bridge so disk is wiped.

Where this sits (platform map)

gittr-mcp is the agent door into the same platform humans use in the browser. You are here = gittr-mcp (this repo, teal). Cyan-outlined host boxes = public hostnames (git. / pages. / relay.gittr.space) (teal = this repo; cyan outline = host URLs).

flowchart TB
  Agent["AI host<br/>Cursor / Claude / …"]
  MCP["★ YOU ARE HERE · gittr-mcp<br/>this repo · agent tools"]
  UI["gittr Client<br/>gittr.space"]
  Bridge["gitnostr Bridge<br/>git.gittr.space<br/>SSH / HTTPS git"]
  RelayGittr["gittr Pyramid relay<br/>relay.gittr.space<br/>wss · open forge + GRASP"]
  Relays["Other Nostr relays"]
  Pages["Pages / nsite<br/>pages.gittr.space"]
  Remote["git remote nostr<br/>optional"]

  Agent -->|MCP tools| MCP
  MCP -->|HTTPS + Nostr auth| Bridge
  MCP -->|sign NIP-34 events| RelayGittr
  MCP -->|sign NIP-34 events| Relays
  UI --> RelayGittr
  UI --> Relays
  UI --> Bridge
  Pages --> Relays
  Remote -.-> Relays

  classDef youAreHere fill:#0f766e,stroke:#5eead4,stroke-width:3px,color:#ecfdf5
  classDef hostUrl fill:#164e63,stroke:#22d3ee,stroke-width:2px,color:#ecfeff
  class MCP youAreHere
  class Bridge,Pages,RelayGittr hostUrl

Addressing for agents: resolveRepoByNostrId(npub|hex, repo) → cloneUrl + relays. Prefer announced npub-path HTTPS on git.gittr.space (NIP-34); hex path is a disk fallback if a symlink is missing. Include wss://relay.gittr.space when publishing.

What you can do (workflows)

These are the processes people actually run; each maps to MCP tools the agent can call. Agents: follow docs/AGENT-WORKFLOW.md (which tool, and what not to call after it).

Ship a new project

1. createRepo — push initial files to the bridge and publish Nostr kinds 30617 + 30618 in one step (best default for agents).
   Pass publicRead: false to create a private repo (code/clone/API/SSH readable only by you and listed maintainers). The announcement name/description still appear on relays — only file access is gated.
2. Or step-by-step: pushToBridge → publishRepoAnnouncement → publishRepoState.

Private repositories

• Set publicRead: false on createRepo, publishRepoAnnouncement, forkRepo, or mirrorRepo.
• Private repos are hidden from Explore/home/profile listings for strangers.
• Direct URL still shows the repo name with a Private badge; unauthorized viewers see a lock screen (no code).
• SSH / CLI / API reads use the same ACL as the web UI: your npub must be owner or maintainer (addCollaborator or Settings → Contributors on gittr.space).
• SSH key registration is unchanged — keys identify you; private repos only check whether your pubkey has read permission.

Day-to-day development

• pushToBridge — update files on a branch (NIP-98 auth to gittr bridge); optional deletedPaths / allowTreeShrink for file or folder deletes (parity with Code-tab trash).
• getFile, bridgeListFiles, bridgeGetFileContent, getBranches, getCommitHistory — read without cloning. getFile is the bridge, then a short GRASP list — not the Code tab. On the website: latest live 30617; forge source is the tree when present (stale bridge listing is replaced); otherwise first non-empty clone[] listing. See MCP-GITTR-PARITY.md and gittr FILE_FETCHING_INSIGHTS.md.
• resolveRepoByNostrId — find clone URLs and relays from npub + repo name.

Issues (bug reports, tasks)

• listIssues, getIssueById — same rows as the website Issues tab. Nostr issues, plus GitHub or Codeberg/Gitea issues when the repo source says so. They stay separate rows. getIssueById with issue-N or a number needs ownerPubkey and repoId. GitLab sources stay Nostr-only.
• createIssue
• listIssueComments, createIssueComment — Nostr comments on a 64-character id. Forge comments when the id is issue-N or a number (read-only; the website does not post them back to GitHub).
• closeIssue, reopenIssue — publish NIP-34 status events (1632 / 1630) for a 64-char Nostr event id. GitHub/Gitea imported issue-12 / pr-12 (and a bare 12) are refused — close those on the origin.

Pull requests (code review flow)

Honest limits on PRs: Creating and listing PRs via MCP is supported. Merging needs git installed and permission on the repo. Some relays are strict about clone URL + relay matching in repo announcements — if PR publish fails, fix metadata (see Limitations) or use createPRViaGittrCLI. Details: docs/DEVELOPER.md#limitations.

Fork, mirror, import

• forkRepo — fork an existing gittr repo under your key.
• mirrorRepo — same result as the website Push of a GitHub/GitLab repo: forge commits on gittr (history kept, and a later call updates them), the same git-server list, and a state event whose HEAD is the forge default branch. A later call keeps the name, description, and web links already announced.
• importRemoteToBridge — copy onto the git server only. With the owner key, a later call updates the forge commits. It does not publish the Nostr card. Use mirrorRepo for the full website result.
• Forge 403 / suspended account: if the repo was already copied, keep using https://git.gittr.space/<npub>/<repo>.git. Do not point mirrorRepo at a new forge to change the source — that copies the new URL onto gittr and replaces the branches. Guide: docs/AGENT-WORKFLOW.md.

Discover & social

• listRepos, searchRepos, myRepos, exploreRepos, getTrendingRepos (trending = recent repos, not engagement rank)
• starRepo, unstarRepo, listStars — NIP-25 on the repo’s 30617 event (same as gittr Star button).
• watchRepo, unwatchRepo, listWatchedRepos — NIP-51 kind 10018 followed-repo list (same as gittr Watch).
• getRepoContributors

Parity details: docs/MCP-GITTR-PARITY.md — what matches gittr.space vs caveats.

Releases & tags

• listReleases — git tags from bridge (refs/tags/*), not the web UI Releases tab and not Zapstore.
• listForgeReleases — forge Releases tab listing (all assets; no NIP-82 MIME gate).
• createRelease — returns guidance only (UI release notes until next 30617 push).
• fetchForgeReleases — one forge Release + announceable binaries. Omit tag for latest; hash:true for sha256 (required before announce).
• announceSoftwareFromForgeRelease — Zapstore/NIP-82 (kinds 32267 / 30063 / 3063) from a tagged forge Release. APK preferred; AppImage/DMG/linux tar.gz/MSI/EXE/IPA also. Extra binaries on the same tag are sibling assets. Copies images: from the forge zapstore.yaml. Optional pinToBlossom (public Blossom; blossom.gittr.space only for official space.gittr.app). Same as gittr Nostr Apps (latest) or Releases Announce on Nostr (tag=). Never a tagless app.
• deleteSoftwareAnnounce — NIP-09 kind 5 for those app/release/asset event ids.

Pages & security

• publishNostrPages — NIP-5A kind 35128 + Blossom upload through gittr (index.html required).
• auditRepoDependencies — parse lockfiles on the bridge and query OSV via gittr /api/security/audit.

Lightning bounties & pay-to-push

• Bounties: listBounties, createBountyInvoice, publishBountyToNostr, submitBounty, listBountiesForIssue, release/withdraw tools.
• Paywall: getPushPaywallStatus, createPushPaywallIntent, syncRepoPushPolicy.
• Optional LNbits: set GITTR_LNBITS_URL and GITTR_LNBITS_ADMIN_KEY in MCP env (see .env.example).

Session / keys

• describeAgentAuth — run once: confirms keys load (never returns nsec); if unconfigured it tells the agent to ask you about a test keypair.
• setupTestKeypair — after your explicit OK, writes a disposable test identity to .nostr-keys.json (replace with your real nsec anytime).
• loadCredentials, getPublicKey — debugging helpers. MCP loadCredentials masks nsec (prefix only), secretKey, and private_key.

Full tool list: 50+ tools in server.js (search for name:). Library API: docs/DEVELOPER.md.

Install (5 minutes)

Requirements

• Node.js 18+
• A Nostr private key (nsec or hex) — same identity you use on gittr.space

1. Get the server

Clone (developers / Cursor):

git clone https://github.com/arbadacarbaYK/gittr-mcp.git
cd gittr-mcp
npm install

Claude Desktop one-click (.mcpb): this package is not on npm. Download the latest bundle from GitHub Releases (gittr-mcp-x.y.z.mcpb) and install that. New releases are built automatically when we push a v* tag — see docs/RELEASE.md.

2. Add your key (local only, never commit)

cp .nostr-keys.json.example .nostr-keys.json

Edit .nostr-keys.json and set your nsec (or hex secretKey). The file is gitignored.

Lookup order: ./.nostr-keys.json (the folder the MCP process was started in) → .nostr-keys.json next to server.js → ~/.nostr-identity.json → ~/.config/gittr/keys.json. On Windows, the home folder is used even when HOME is unset. A UTF-8 BOM (PowerShell’s default) is stripped before the file is read.

No key yet? Test keypair flow. If no credentials are found, describeAgentAuth and all key-missing errors tell the agent to ask you whether a disposable test keypair should be created. If you agree, the agent calls setupTestKeypair({ confirm: true }) — it writes a fresh identity into .nostr-keys.json (flagged "generated": true, file mode 600, never committed) and everything auto-loads it from then on. Replace the nsec in that file with your real key whenever you're ready; describeAgentAuth keeps reminding the agent that a test key is active. It never runs without confirm: true and never overwrites existing credentials unless you explicitly ask for force: true — anything published under a keypair stays under that identity forever, so this is always your call, not the agent's.

3. Wire up your MCP host

Important: Add a new server entry — do not replace your entire MCP config.

Cursor

Edit ~/.cursor/mcp.json (or project MCP settings). Use an absolute path:

{
  "mcpServers": {
    "gittr": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gittr-mcp/server.js"],
      "env": {
        "BRIDGE_URL": "https://gittr.space"
      }
    }
  }
}

Reload MCP or restart Cursor.

Claude Desktop

Quit Claude, edit claude_desktop_config.json (path depends on OS — see Anthropic docs), same mcpServers block as above, restart.

VS Code / Copilot, Windsurf, OpenClaw, custom apps

Same stdio contract: command: node, args: ["/path/to/server.js"], optional env.
OpenClaw / mcporter: docs/MCP-HOSTS.md.

Embed as a library (no MCP)

const gittr = require('gittr-mcp');
await gittr.pushToBridge({ /* ... */ });

Entry point: index.js. MCP process: server.js (npm bin gittr-mcp).

4. Verify

In chat, ask the agent to call describeAgentAuth, or from the repo:

npm test                 # full package (includes clone-set + forge-match regressions)
npm run test:regressions # fast: grasp clone URLs + findReposBySource matchers
npm run test:mcp-stdio   # optional live stdio CallTool matrix

UI / file-fetch tip fidelity regressions live in the gittr monorepo: cd ../gittr/ui && npm run test:regressions (see gittr docs/FILE_FETCHING_INSIGHTS.md).

What to ask your agent

Examples that map to the workflows above:

• “Create a repo my-demo with a README and publish it on gittr.”
• “Push these file changes to my-demo on main.”
• “Open an issue: login button broken.”
• “List open PRs on npub…/my-demo and merge PR <id> if I’m the owner.”
• “Mirror https://github.com/user/repo to gittr as repo-name.”

Agents should read tool results as JSON; many responses include agentSummary and nextSteps.

Limitations (PRs & clone URLs)

Short version — full detail in docs/DEVELOPER.md:

1. Bridge push and Nostr publish are separate steps unless you use createRepo. Pushing alone does not make the repo visible everywhere.
2. git clone only “works” for others if your published clone URL serves git HTTP. This MCP defaults toward https://git.gittr.space/<hex-pubkey>/<repo>.git. A failed clone means fix the URL in 30617, not “ignore and continue.” Host-only values like https://git.gittr.space are rejected/expanded on publish.
3. mergePullRequest needs git on the machine running MCP and maintainer/owner rights.
4. Relays can rate-limit or lag; failed verification is a failed publish, not “maybe OK.”
5. Same result as the website Push. mirrorRepo copies the forge commits (and updates them if the repo is already there), then writes clone for gittr, ngit, gitnostr, shakespeare, and danconway, keeps the forge URL in source, and publishes the branch tips with HEAD on the forge default branch. A second call keeps the existing name, description, and web links. Dead hosts (git-01.uid.ovh, ngit-relay.nostrver.se) are not added.
6. pushToBridge replaces the branch with one new snapshot (author gittr push) and drops imported GitHub history. That matches editing files on the website, not syncing GitHub. Do not use it after mirrorRepo.

Do MCP users get gittr’s filter / CORS server fixes?

Mostly yes, without updating MCP. Browser/filter/uploadpack/CORS fixes live on git.gittr.space. Anyone (including agents via MCP) cloning that host benefits as soon as the server is fixed.

MCP updates are a new version, not an npm package. This project is not installed from the npm registry. Cursor runs node on a local server.js. Claude can install the .mcpb file from GitHub Releases.

• Cursor: in the folder whose path ends with gittr-mcp/server.js, run git pull, then reload the MCP. npm install is only the first-time library download in that folder. A normal update does not need it.
• Release file: install the new gittr-mcp-x.y.z.mcpb from Releases. The old 1.0.9 file does not include later fixes. The version shown at startup is the way to tell them apart.

For developers

npm ci
npm test
# Live tests (real relays; optional LNbits) — see .env.example
GITTR_TEST_NSEC=nsec1... npm run test:live:matrix

Security

• Do not commit .nostr-keys.json, .env, or real nsec values.
• Bridge auth uses NIP-98; treat agent transcripts as sensitive.
• Only .nostr-keys.json.example belongs in git.
• The gittr Dependencies tab can list matches inside the MCP SDK. gittr-mcp talks stdio only (it is a server, not an OAuth client). @modelcontextprotocol/sdk stays on ^1.32.1 or newer so CVE-2026-104850 is not in the lockfile, and patched fast-uri / hono / qs stay pinned in overrides. Details: docs/SECURITY-ADVISORIES.md.

Links

• This repo: https://github.com/arbadacarbaYK/gittr-mcp
• gittr.space: https://gittr.space
• Glama: https://glama.ai/mcp/servers/arbadacarbaYK/gittr-mcp
• Awesome MCP Servers: https://github.com/punkpeye/awesome-mcp-servers (Version Control)
• NIP-34 (git on Nostr): https://github.com/nostr-protocol/nips/blob/master/34.md

See LICENSE (MIT).