Snapshot MCP

A Model Context Protocol server for Snapshot. Lets AI assistants read governance data (spaces, proposals, votes, voting power) and act on the user's behalf (cast votes, create proposals, follow spaces) through Snapshot's GraphQL API. Available as a hosted endpoint at https://mcp.snapshot.box, or self-hostable.

Tools

snapshot-query

Runs any GraphQL query against the Snapshot API. The user's address is auto-bound as $user — declare it in the query and reference it; do not pass it in variables.

Input	Type	Description
query	string	GraphQL query string
variables	object?	GraphQL variables

Example — fetch active proposals for a space:

query ($space: String!) {
  proposals(first: 10, where: { space: $space, state: "active" }) {
    id
    title
    choices
    scores
    votes
    end
  }
}

snapshot-schema

Returns the Snapshot GraphQL schema. Call this before snapshot-query only when a query fails on an unknown field or filter. The response is large, so do not call it preemptively.

No inputs.

snapshot-vote

Casts a vote on a Snapshot proposal. The proposal's voting type and privacy are fetched from Snapshot and applied automatically, so the caller does not need to specify them. Re-calling on the same proposal replaces the previous vote (this is how the user changes a vote).

Input	Type	Description
space	string	Space ID slug (e.g. "ens.eth")
proposal	string	Proposal ID (hex string)
choice	number | number[] | object	A number for basic/single-choice, an array of indices for approval/ranked-choice, or { "1": weight, "2": weight, ... } for weighted/quadratic
reason	string?	Reason for the vote. Ignored on Shutter-encrypted proposals.

Requires a wallet to be configured for signing (see Configuration). On HTTP, this is the OAuth-managed CDP alias; on stdio, it is the ALIAS_PRIVATE_KEY. If the user has not yet authorized the alias, the tool returns the authorization URL for them to visit.

snapshot-propose

Creates a Snapshot proposal. Most defaults come from the space itself, so for typical use you only need space, title, and body. The space's enforced voting type, voting period, snapshot block, and privacy mode are read from Snapshot and applied automatically.

Input	Type	Description
space	string	Space ID slug (e.g. "ens.eth")
title	string	Proposal title
body	string?	Proposal body (markdown)
discussion	string?	Discussion link
type	string?	One of basic, single-choice, approval, ranked-choice, weighted, quadratic. Defaults to whatever the space enforces, or basic.
choices	string[]?	Vote choices. Defaults to ["For", "Against", "Abstain"] for basic; required for any other type.
labels	string[]?	Proposal label IDs
start	number?	Voting start as a unix timestamp in seconds. Defaults to now + space.voting.delay.
end	number?	Voting end as a unix timestamp in seconds. Defaults to start + space.voting.period (3 days if the space sets none).
shielded	boolean?	Opt into Shutter-encrypted voting. Only honored when the space's voting.privacy is "any"; spaces with voting.privacy === "shutter" always encrypt.

The snapshot block is read from https://rpc.snapshot.org/<chainId> based on the space's network. Requires a wallet, same as snapshot-vote.

snapshot-follow

Adds a space to the user's followed list. Calling it again on a space the user already follows is safe — Snapshot does not duplicate the follow.

Input	Type	Description
space	string	Space ID slug (e.g. "ens.eth")

Requires a wallet, same as snapshot-vote and snapshot-propose.

Usage

Hosted (Claude Desktop / Claude.ai)

{
  "mcpServers": {
    "snapshot": {
      "type": "http",
      "url": "https://mcp.snapshot.box"
    }
  }
}

Self-hosting

Requirements: Bun ≥ 1.0.0

bun install

HTTP server

bun start

Listens on port 8080 by default (override with PORT env var).

Stdio (local)

bun run stdio

Claude Desktop config example:

{
  "mcpServers": {
    "snapshot": {
      "command": "bun",
      "args": ["src/index.ts", "--stdio"],
      "cwd": "/path/to/snapshot-mcp",
      "env": {
        "ALIAS_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Configuration

Copy .env.example to .env and configure:

Variable	Description
SNAPSHOT_API_KEY	Snapshot API key for higher rate limits (optional)
SNAPSHOT_API_URL	GraphQL endpoint (default https://hub.snapshot.org/graphql)
PORT	HTTP server port (default: 8080)
BASE_URL	Public URL for OAuth metadata (e.g. https://mcp.snapshot.box)
JWT_SECRET	HS256 secret used to sign access tokens — required for HTTP mode (≥32 chars; openssl rand -hex 32)
CDP_API_KEY_ID	Coinbase CDP API key ID — required for HTTP mode
CDP_API_KEY_SECRET	Coinbase CDP API key secret — required for HTTP mode
CDP_WALLET_SECRET	Coinbase CDP wallet secret — required for HTTP mode
ALIAS_PRIVATE_KEY	Single private key — stdio mode only (ignored by HTTP server)

The HTTP server requires CDP credentials and a JWT secret. Each user who connects via OAuth gets their own CDP-managed alias wallet, so votes can only be signed by the user who authorized the specific alias. Access tokens are stateless JWTs (HS256) signed with JWT_SECRET; rotating that secret invalidates every issued token.

Auth flow

HTTP (Claude Desktop / Claude.ai) — OAuth 2.0

The HTTP server exposes OAuth 2.0 endpoints. Claude Desktop and Claude.ai will show a "Connect" button that triggers the flow automatically:

1. Claude redirects to /authorize
2. Server mints a fresh per-session CDP alias wallet and redirects to snapshot.box/#/settings/alias/authorize/<alias> with a callback URL
3. User authorizes that alias on Snapshot
4. Snapshot redirects back to /auth/callback
5. Server resolves the authorizing user from the alias, generates an auth code, and redirects back to Claude
6. Claude exchanges the code for a JWT (HS256) access token at /token
7. All subsequent requests include the token — the server verifies the signature and reads the user and their CDP account from the claims

Each user gets their own CDP alias, so one user cannot sign votes on behalf of another. Tokens are self-verifiable and survive server restarts (until JWT_SECRET rotates).

Stdio (local)

1. Call snapshot-vote — if not yet authorized, returns the authorization URL
2. User visits snapshot.box/#/settings/alias/authorize/<alias> to authorize
3. Call snapshot-vote again — works

Development

bun dev      # watch mode
bun test     # run security tests
bun lint     # ESLint
bun format   # Prettier