Skip to content

About

Cloudflare Worker serving read-only pump.fun token tools to AI agents over MCP Streamable HTTP.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

20 stars

Watchers

0 watching

Forks

Repository files navigation

Pump.fun MCP Server

GitHub stars Last commit PRs welcome AI agent friendly

A Cloudflare Worker that implements the MCP Streamable HTTP transport for AI agents to read pump.fun data on Solana. It is stateless: every request is answered on its own, with no sessions.

Tools (10 read-only tools)

Tool Description Source
searchTokens Search tokens by name, symbol, or mint address pump.fun API
getTokenDetails Full details for a specific token pump.fun API
getBondingCurve Bonding curve read on-chain: reserves, spot price, market cap in SOL, exact graduation progress; for graduated coins, their PumpSwap pool Solana RPC
getTokenTrades Recent trade history (buys and sells), with offset pagination pump.fun API
getTrendingTokens Top tokens by market cap pump.fun API
getNewTokens Most recently launched tokens pump.fun API
getGraduatedTokens Graduated tokens among the 50 largest by market cap pump.fun API
getKingOfTheHill Highest market cap token still on its bonding curve pump.fun API
getCreatorProfile Tokens by a creator wallet, with a heuristic risk note pump.fun API
getTokenHolders Largest holders as a share of total supply, grouped by owner wallet, with the bonding-curve and PumpSwap pool vaults labelled Solana RPC

All tools are read-only: no wallet keys needed. Write operations (buy/sell/create) require client-side wallet signing and are intentionally excluded for safety. Every argument is validated (addresses must be 32-byte base58 keys, counts are bounded integers) before any upstream request.

How the on-chain numbers are derived:

  • Bonding curve. The curve account is the PDA ["bonding-curve", mint] of the pump program, decoded per the pump IDL. Spot price is virtual_quote_reserves / virtual_token_reserves; market cap is spot price times total supply. A curve completes when real_token_reserves reaches 0, so graduation progress is the share of the curve's initial real token reserves already sold, computed exactly with the Global account's parameters. Curves created with other parameters report progress as unknown rather than a guess.
  • Holders. getTokenLargestAccounts returns at most the 20 largest token accounts. Each account is resolved to its owner, accounts with the same owner are added together, and shares are measured against getTokenSupply. The bonding-curve vault and the canonical PumpSwap pool vault are labelled and left out of the top-5 concentration figure.

The pump.fun frontend API sits behind a bot challenge that can refuse datacenter traffic. When it does, the API-backed tools return a clear error; the two Solana RPC tools are unaffected.

Deploy

npm install
npx wrangler deploy

Configuration

Name Kind Purpose
SOLANA_RPC_URL variable or secret Solana RPC endpoint. The default public endpoint rate-limits getTokenLargestAccounts heavily; use a paid RPC in production. A keyed URL is a credential: remove it from [vars] and run npx wrangler secret put SOLANA_RPC_URL. The Worker never echoes this URL in errors.
PUMP_API_URL variable pump.fun frontend API base URL.
ALLOWED_ORIGINS variable (optional) Comma-separated browser origins allowed to call /mcp, or *. Unset: the built-in allowlist (SperaxOS and LobeHub). Clients that send no Origin header are unaffected.
RATE_LIMITER rate limit binding Per-IP limit on POST /mcp (60 requests per minute in wrangler.toml). Optional in code.

Custom domain

To serve at pump-fun-sdk.modelcontextprotocol.name (or any subdomain):

  1. Add a CNAME record in Cloudflare DNS pointing to your Worker
  2. Add a Custom Domain in the Cloudflare dashboard under Workers, pump-fun-mcp, Settings, Domains & Routes

Or for the path-based gateway pattern (modelcontextprotocol.name/mcp/pump-fun-sdk):

  1. Uncomment the [route] section in wrangler.toml
  2. Redeploy

Connect from SperaxOS

The server is registered in cryptoMcpData.ts and appears in the MCP marketplace. Users can also add it manually:

https://pump-fun-sdk.modelcontextprotocol.name/mcp

From Claude Code: claude mcp add --transport http pump-fun https://<your-worker>/mcp.

Transport behaviour

  • POST /mcp takes one JSON-RPC message, or a batch of up to 16, and answers with application/json.
  • Notifications and client responses get 202 Accepted with no body.
  • GET and DELETE on /mcp return 405: the server opens no server-to-client stream and keeps no sessions.
  • initialize echoes the client's protocol version when supported (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) and otherwise offers the latest. An unsupported MCP-Protocol-Version header gets 400.
  • A browser Origin outside the allowlist gets 403. Bodies over 64 KiB get 413, non-JSON content types 415, and an Accept header that excludes JSON 406. A rate-limited client gets 429 with Retry-After.
  • Bad tool arguments come back as a tool result with isError: true, so the model can correct them; an unknown tool is a JSON-RPC -32602 error.

GET / (also /.well-known/mcp and /.well-known/mcp.json) returns a discovery manifest.

Development

npm run dev     # wrangler dev, local server on :8787
npm run check   # lint, typecheck, tests, and a wrangler dry-run bundle (what CI runs)

Tests use node --test on the TypeScript sources directly (Node 22.18 or newer) and stub every upstream call.

Test with curl:

# Discovery manifest
curl http://localhost:8787/

# Initialize
curl -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# List tools
curl -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Bonding curve, read on-chain
curl -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getBondingCurve","arguments":{"mint":"<mint address>"}}}'

Architecture

AI Agent (SperaxOS, Claude, ...)
    │
    ▼
Cloudflare Worker (MCP Streamable HTTP, stateless)
    │
    ├── pump.fun API (search, listings, token details, trades)
    │   └── frontend-api-v3.pump.fun
    │
    └── Solana RPC (bonding curves, holders, supply)
        └── SOLANA_RPC_URL

Source layout: src/index.ts (HTTP transport), src/mcp.ts (JSON-RPC and MCP methods), src/tools.ts (tool schemas), src/executor.ts (tool handlers), src/validation.ts (argument checks), src/pumpApi.ts (pump.fun API client), src/solana.ts (RPC client and PDA derivation), src/curve.ts (bonding-curve decoding and math), src/holders.ts (holder arithmetic), src/format.ts (output hygiene).

Star History

Star History Chart

Support the project

If pump-fun-workers saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/pump-fun-workers and it has the context it needs.

More from the same author

Contributors

Contributors


Built by nirholas · @nichxbt · github.com/nirholas

About

Cloudflare Worker serving read-only pump.fun token tools to AI agents over MCP Streamable HTTP.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

20 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

⌂ 换网址