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 do write the bridge when you want hosted git — put https://git.gittr.space/… in clone[]. 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.

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, createIssue, getIssueById
• listIssueComments, createIssueComment — NIP-22 kind 1111 (same tags as gittr issue threads). Does not touch bounties.
• 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 — copy from GitHub/GitLab URL to gittr.
• importRemoteToBridge — server-side import/refetch into bridge storage.

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.