{"id":50440621,"url":"https://github.com/convex-dev/convex-plugin","last_synced_at":"2026-05-31T19:01:10.782Z","repository":{"id":351160810,"uuid":"1209803979","full_name":"Convex-Dev/convex-plugin","owner":"Convex-Dev","description":"Convex Plugin for Claude","archived":false,"fork":false,"pushed_at":"2026-04-13T20:17:53.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-13T22:14:17.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Convex-Dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T19:51:37.000Z","updated_at":"2026-04-13T20:17:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Convex-Dev/convex-plugin","commit_stats":null,"previous_names":["convex-dev/convex-plugin"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Convex-Dev/convex-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Fconvex-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Fconvex-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Fconvex-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Fconvex-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Convex-Dev","download_url":"https://codeload.github.com/Convex-Dev/convex-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Fconvex-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33744447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T19:01:08.821Z","updated_at":"2026-05-31T19:01:10.773Z","avatar_url":"https://github.com/Convex-Dev.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Convex Plugin for Claude Code\n\nConnect Claude Code to a [Convex](https://convex.world) peer via the Model Context Protocol. Once installed, Claude can query the lattice, run transactions, manage accounts and keys, resolve CNS names, and watch on-chain state in real time. The plugin also injects Convex terminology and conventions so generated code and explanations stay consistent with the platform.\n\nConvex is a lattice-based decentralised network with a lambda-calculus virtual machine, Convergent Proof of Stake consensus, and millisecond finality. See the [documentation](https://docs.convex.world) for background.\n\n## Install\n\n```bash\nclaude plugin install https://github.com/Convex-Dev/convex-plugin\n```\n\nOr, for local development against an unpublished copy:\n\n```bash\nclaude --plugin-dir ./convex-plugin\n```\n\n## What you get\n\n- **MCP tools** served by the peer — the full current set, including queries, transactions, cryptography, encoding, account management, signing-service operations, and state watches.\n- **MCP prompts** — guided workflows such as account exploration, network status, creating accounts, deploying contracts, and transferring funds.\n- **CLAUDE.md context** — Convex terminology (juice not gas, copper, peer not miner, lattice not blockchain), British English spelling, and tool-selection hints so Claude picks the right MCP tool the first time.\n- **Slash commands** — `/convex:explore`, `/convex:faucet`, `/convex:sign`, `/convex:transact` wrap common flows. The sign/transact pair delegates Ed25519 signing to your local `convex-cli` keystore so private keys never leave your machine.\n\n## Configuration\n\nThe plugin registers two MCP servers so you can switch between networks without editing anything:\n\n| Server            | Default URL                                              | Override env var          |\n| ----------------- | -------------------------------------------------------- | ------------------------- |\n| `convex-testnet`  | `https://mikera1337-convex-testnet.hf.space/mcp`         | `CONVEX_PEER_URL`         |\n| `convex-local`    | `http://localhost:8080/mcp`                              | `CONVEX_LOCAL_URL`        |\n\nAuth tokens (optional — read-only tools work without one):\n\n| Variable                   | Applies to        |\n| -------------------------- | ----------------- |\n| `CONVEX_AUTH_TOKEN`        | `convex-testnet`  |\n| `CONVEX_LOCAL_AUTH_TOKEN`  | `convex-local`    |\n\nExample — point the testnet binding at your own hosted peer:\n\n```bash\nexport CONVEX_PEER_URL=https://peer.example.com/mcp\nexport CONVEX_AUTH_TOKEN=your_token_here\nclaude\n```\n\nDisable a server you don't need via Claude Code's `/mcp` panel.\n\n## Running a local peer\n\nThe `convex-local` binding connects to `http://localhost:8080/mcp` — the default REST API port of a Convex peer. To run one locally:\n\n```bash\n# Download or build convex.jar (see https://github.com/Convex-Dev/convex)\njava -jar convex.jar local start\n```\n\nThat starts a single-peer local lattice with the peer binary protocol on `18888` and the REST/MCP endpoint on `8080`. Open Claude Code and the `convex-local` tools will be live.\n\nNotes for local development:\n\n- **No HTTPS.** The plugin does not block seed-based tools over `http://localhost`, but you should treat local keys as disposable. Do not point `CONVEX_LOCAL_URL` at a plain-HTTP non-localhost peer.\n- **Faucet.** `convex local start` configures a faucet by default; `/convex:faucet` works against `convex-local` once you override it to target the local server.\n- **Signing service.** Not enabled by default on local peers — the 13 `signing*` tools will be absent unless you configure one. The core 22 tools always work.\n- **Custom port.** If you run the peer on a non-default port, set `CONVEX_LOCAL_URL=http://localhost:NNNN/mcp` before launching Claude Code.\n\n## Security notes\n\n- **HTTPS is required for seed-based tools** (`transact`, `signAndSubmit`, `transfer`) since they transmit Ed25519 seeds. Do not point the plugin at a plain-`http://` peer for any signing work beyond local development.\n- **The signing service keeps private keys server-side** and never returns raw seeds; elevated operations (import, export, delete, change-passphrase) require an interactive browser confirmation.\n- **Choose a peer you trust.** A malicious peer can return misleading query results or refuse to submit your transactions. For production use, run your own peer.\n\n## Troubleshooting\n\n**\"Connection refused\" / peer unreachable** — check that your peer is running and reachable from the machine Claude Code is on: `curl $CONVEX_PEER_URL/.well-known/mcp`. For local peers, confirm the port matches `CONVEX_LOCAL_URL`.\n\n**Tools don't appear** — restart Claude Code after changing env vars. Use `/mcp` to list active servers and inspect connection status.\n\n**Slow testnet** — the public HF testnet can be slow to cold-start. Raise the MCP timeout:\n\n```bash\nMCP_TIMEOUT=30000 claude\n```\n\n**`401 Unauthorized`** — the peer requires auth. Set `CONVEX_AUTH_TOKEN` (or `CONVEX_LOCAL_AUTH_TOKEN`) to a valid bearer token.\n\n**`403 Forbidden: invalid origin`** — the peer is enforcing Origin-header restrictions. Claude Code sends no Origin header by default, so this usually means the peer is misconfigured; see [CAD041 security notes](https://docs.convex.world/docs/cad/041_mcp) on origin handling.\n\n**Elevated signing operation opened a browser** — this is expected for `signingImportKey`, `signingExportKey`, `signingDeleteKey`, and `signingChangePassphrase`. Approve in the browser and the tool call will resume.\n\n## Requirements\n\n- Claude Code installed (`claude --version`)\n- A reachable Convex peer serving the MCP endpoint (part of `convex-restapi` since 2025)\n- Java is not required on the client — the plugin only speaks HTTP to the peer\n\n## Related\n\n- [Convex core](https://github.com/Convex-Dev/convex) — peer implementation and MCP server\n- [CAD041: Model Context Protocol](https://docs.convex.world/docs/cad/041_mcp) — specification\n- [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25)\n\n## Licence\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconvex-dev%2Fconvex-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconvex-dev%2Fconvex-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconvex-dev%2Fconvex-plugin/lists"}