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.

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).

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.

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.

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

Related MCP server: MCP Snapshot Server

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:

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