Skip to content
Back to search

pacifica-mcp

A Model Context Protocol server for the Pacifica perpetual-futures exchange. It exposes Pacifica's REST API — market data, account and position queries, and full order management — as MCP tools, so…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pacifica-fi--pacifica-mcp/badge.svg)](/listings/pacifica-fi--pacifica-mcp)

HTML

<a href="/listings/pacifica-fi--pacifica-mcp"><img src="/api/listings/pacifica-fi--pacifica-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Node.js 22.23.4+, 24.22.1+, or 26.12.1+** on a supported release line (Node 24 LTS recommended). - Update the Node.js runtime used by your MCP client and restart the server. Updating this npm package does not update Node.js. - A **Pacifica account address** (your main account or a subaccount) - For trading (optional): a signing key — either your main wallet's secret key or, recommended, a revocable **agent key** bound to your account

Install

Every MCP client runs the server the same way — the command is `npx -y @pacifica-fi/mcp-server` with the environment variables `ADDRESS` plus `AGENT_PRIVATE_KEY` or `PRIVATE_KEY` (omit the key for read-only). The `npx -y` command downloads and runs the latest published version automatically, so there is no manual install step. Only the config format differs per client; the examples below use agent-key mode, so swap in `PRIVATE_KEY`, or drop the key entirely for read-only (see [Environment variables](#environment-variables) and [Modes](#modes)).

On startup the server logs the active account and auth mode to stderr (visible in your client's MCP logs), e.g. `[pacifica-mcp] account=<address> mode=agent-key`.

> **Network:** by default the server targets the Pacifica **testnet** > (`https://test-api.pacifica.fi`). To trade on production, set > `PACIFICA_BASE_URL=https://api.pacifica.fi` (see the > [environment variables](#environment-variables) below).

Claude Desktop

Open Claude Desktop → **Settings → Developer → Edit Config** and add the server to `claude_desktop_config.json`:

{
  "mcpServers": {
    "pacifica": {
      "command": "npx",
      "args": ["-y", "@pacifica-fi/mcp-server"],
      "env": {
        "ADDRESS": "<your Solana account address>",
        "AGENT_PRIVATE_KEY": "<your base58 agent wallet secret key>"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Add it with the CLI:

claude mcp add pacifica \
  --transport stdio \
  --env ADDRESS=<your account address> \
  --env AGENT_PRIVATE_KEY=<your agent wallet secret key> \
  -- npx -y @pacifica-fi/mcp-server

Or create `.mcp.json` in your project root (commit it to share with your team):

{
  "mcpServers": {
    "pacifica": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pacifica-fi/mcp-server"],
      "env": {
        "ADDRESS": "<your account address>",
        "AGENT_PRIVATE_KEY": "<your agent wallet secret key>"
      }
    }
  }
}

Verify with `claude mcp list`. Docs: <https://code.claude.com/docs/en/mcp>

OpenAI Codex

Add it with the CLI:

codex mcp add pacifica \
  --env ADDRESS=<your account address> \
  --env AGENT_PRIVATE_KEY=<your agent wallet secret key> \
  -- npx -y @pacifica-fi/mcp-server

Or edit `~/.codex/config.toml` (note the nested `.env` table):

[mcp_servers.pacifica]
command = "npx"
args = ["-y", "@pacifica-fi/mcp-server"]

[mcp_servers.pacifica.env]
ADDRESS = "<your account address>"
AGENT_PRIVATE_KEY = "<your agent wallet secret key>"

Docs: <https://developers.openai.com/codex/mcp>

Factory (droid)

Add it with the CLI:

droid mcp add pacifica "npx -y @pacifica-fi/mcp-server" \
  --env ADDRESS=<your account address> \
  --env AGENT_PRIVATE_KEY=<your agent wallet secret key>

Or edit `~/.factory/mcp.json` (user-level) or `.factory/mcp.json` (project-level):

{
  "mcpServers": {
    "pacifica": {
      "command": "npx",
      "args": ["-y", "@pacifica-fi/mcp-server"],
      "env": {
        "ADDRESS": "<your account address>",
        "AGENT_PRIVATE_KEY": "<your agent wallet secret key>"
      }
    }
  }
}

Docs: <https://docs.factory.ai/cli/configuration/mcp>

Hermes Agent

Edit `~/.hermes/config.yaml` (YAML, top-level `mcp_servers` key):

mcp_servers:
  pacifica:
    command: "npx"
    args: ["-y", "@pacifica-fi/mcp-server"]
    env:
      ADDRESS: "<your account address>"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 284 lines
  1. # Pacifica MCP Server
  2. A [Model Context Protocol](https://modelcontextprotocol.io) server for the
  3. [Pacifica](https://pacifica.fi) perpetual-futures exchange. It exposes Pacifica's
  4. REST API — market data, account and position queries, and full order management —
  5. as MCP tools, so an MCP client such as Claude Desktop can read the markets and
  6. place trades on your behalf.
  7. ## Getting started
  8. ### Prerequisites
  9. - **Node.js 22.23.4+, 24.22.1+, or 26.12.1+** on a supported release line (Node 24 LTS recommended).
  10. - Update the Node.js runtime used by your MCP client and restart the server.
  11. Updating this npm package does not update Node.js.
  12. - A **Pacifica account address** (your main account or a subaccount)
  13. - For trading (optional): a signing key — either your main wallet's secret key
  14. or, recommended, a revocable **agent key** bound to your account
  15. ### Install
  16. Every MCP client runs the server the same way — the command is
  17. `npx -y @pacifica-fi/mcp-server` with the environment variables `ADDRESS` plus
  18. `AGENT_PRIVATE_KEY` or `PRIVATE_KEY` (omit the key for read-only). The `npx -y`
  19. command downloads and runs the latest published version automatically, so there
  20. is no manual install step. Only the config format differs per client; the examples
  21. below use agent-key mode, so swap in `PRIVATE_KEY`, or drop the key entirely for
  22. read-only (see [Environment variables](#environment-variables) and
  23. [Modes](#modes)).
  24. On startup the server logs the active account and auth mode to stderr (visible in
  25. your client's MCP logs), e.g. `[pacifica-mcp] account=<address> mode=agent-key`.
  26. > **Network:** by default the server targets the Pacifica **testnet**
  27. > (`https://test-api.pacifica.fi`). To trade on production, set
  28. > `PACIFICA_BASE_URL=https://api.pacifica.fi` (see the
  29. > [environment variables](#environment-variables) below).
  30. #### Claude Desktop
  31. Open Claude Desktop → **Settings → Developer → Edit Config** and add the server
  32. to `claude_desktop_config.json`:
  33. ```json
  34. {
  35. "mcpServers": {
  36. "pacifica": {
  37. "command": "npx",
  38. "args": ["-y", "@pacifica-fi/mcp-server"],
  39. "env": {
  40. "ADDRESS": "<your Solana account address>",
  41. "AGENT_PRIVATE_KEY": "<your base58 agent wallet secret key>"
  42. }
  43. }
  44. }
  45. }
  46. ```
  47. Restart Claude Desktop after saving.
  48. #### Claude Code
  49. Add it with the CLI:
  50. ```bash
  51. claude mcp add pacifica \
  52. --transport stdio \
  53. --env ADDRESS=<your account address> \
  54. --env AGENT_PRIVATE_KEY=<your agent wallet secret key> \
  55. -- npx -y @pacifica-fi/mcp-server
  56. ```
  57. Or create `.mcp.json` in your project root (commit it to share with your team):
  58. ```json
  59. {
  60. "mcpServers": {
  61. "pacifica": {
  62. "type": "stdio",
  63. "command": "npx",
  64. "args": ["-y", "@pacifica-fi/mcp-server"],
  65. "env": {
  66. "ADDRESS": "<your account address>",
  67. "AGENT_PRIVATE_KEY": "<your agent wallet secret key>"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. Verify with `claude mcp list`. Docs: <https://code.claude.com/docs/en/mcp>
  74. #### OpenAI Codex
  75. Add it with the CLI:
  76. ```bash
  77. codex mcp add pacifica \
  78. --env ADDRESS=<your account address> \
  79. --env AGENT_PRIVATE_KEY=<your agent wallet secret key> \
  80. -- npx -y @pacifica-fi/mcp-server
  81. ```
  82. Or edit `~/.codex/config.toml` (note the nested `.env` table):
  83. ```toml
  84. [mcp_servers.pacifica]
  85. command = "npx"
  86. args = ["-y", "@pacifica-fi/mcp-server"]
  87. [mcp_servers.pacifica.env]
  88. ADDRESS = "<your account address>"
  89. AGENT_PRIVATE_KEY = "<your agent wallet secret key>"
  90. ```
  91. Docs: <https://developers.openai.com/codex/mcp>
  92. #### Factory (droid)
  93. Add it with the CLI:
  94. ```bash
  95. droid mcp add pacifica "npx -y @pacifica-fi/mcp-server" \
  96. --env ADDRESS=<your account address> \
  97. --env AGENT_PRIVATE_KEY=<your agent wallet secret key>
  98. ```
  99. Or edit `~/.factory/mcp.json` (user-level) or `.factory/mcp.json` (project-level):
  100. ```json
  101. {
  102. "mcpServers": {
  103. "pacifica": {
  104. "command": "npx",
  105. "args": ["-y", "@pacifica-fi/mcp-server"],
  106. "env": {
  107. "ADDRESS": "<your account address>",
  108. "AGENT_PRIVATE_KEY": "<your agent wallet secret key>"
  109. }
  110. }
  111. }
  112. }
  113. ```
  114. Docs: <https://docs.factory.ai/cli/configuration/mcp>
  115. #### Hermes Agent
  116. Edit `~/.hermes/config.yaml` (YAML, top-level `mcp_servers` key):
  117. ```yaml
  118. mcp_servers:
  119. pacifica:
  120. command: "npx"
  121. args: ["-y", "@pacifica-fi/mcp-server"]
  122. env:
  123. ADDRESS: "<your account address>"
  124. AGENT_PRIVATE_KEY: "<your agent wallet secret key>"
  125. ```
  126. Reload with `/reload-mcp` inside Hermes, or restart it.
  127. Docs: <https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp>
  128. #### Crush
  129. Edit `crush.json` in your project root (or `~/.config/crush/crush.json` for all projects).
  130. The top-level key is `mcp` (not `mcpServers`), and Crush expands `$VAR` shell references
  131. in values — so keep secrets in your environment rather than in the file:
  132. ```json
  133. {
  134. "$schema": "https://charm.land/crush.json",
  135. "mcp": {
  136. "pacifica": {
  137. "type": "stdio",
  138. "command": "npx",
  139. "args": ["-y", "@pacifica-fi/mcp-server"],
  140. "env": {
  141. "ADDRESS": "$PACIFICA_ADDRESS",
  142. "AGENT_PRIVATE_KEY": "$PACIFICA_AGENT_PRIVATE_KEY"
  143. }
  144. }
  145. }
  146. }
  147. ```
  148. Docs: <https://github.com/charmbracelet/crush>
  149. ## Environment variables
  150. | Variable | Required | Description |
  151. |---|---|---|
  152. | `ADDRESS` | yes | Public address the actions apply to — your main account or a subaccount. Sent as the `account` field. |
  153. | `PRIVATE_KEY` | no | Base58 Solana secret key (Ed25519) of the main account. Signs POST requests when no agent key is set. |
  154. | `AGENT_PRIVATE_KEY` | no | Base58 secret key of an API **agent wallet** (revocable). When set, signs POST requests and sends `agent_wallet`, so you never expose your main key. The agent must already be bound to `ADDRESS`. Takes precedence over `PRIVATE_KEY`. |
  155. | `AGENT_WALLET` | no | Agent wallet public key. Defaults to the value derived from `AGENT_PRIVATE_KEY`; only set this to override. |
  156. | `PACIFICA_BASE_URL` | no | API host. Defaults to testnet `https://test-api.pacifica.fi`. Set to `https://api.pacifica.fi` for production. |
  157. ## Modes
  158. The server picks a mode from the keys you provide:
  159. - **Read-only** — set only `ADDRESS`. All read (GET) tools work; write (POST) tools
  160. return a clear "read-only mode" error.
  161. - **Agent-key (recommended)** — set `ADDRESS` + `AGENT_PRIVATE_KEY`. Full trading
  162. without ever putting your main wallet's private key in the config.
  163. - **Main-key** — set `ADDRESS` + `PRIVATE_KEY`. Full trading, signing with the main
  164. wallet key (legacy behavior).
  165. ### Recommended: agent key
  166. An agent key is a revocable key bound to your account: it can trade, but it cannot
  167. move funds the way your main wallet can, and you can revoke it at any time. Generate
  168. and bind one once at [app.pacifica.fi/apikey](https://app.pacifica.fi/apikey) — you
  169. sign the binding in-browser, so your main secret never leaves your wallet. Then
  170. configure the MCP with only your account address and the agent key:
  171. ```json
  172. {
  173. "mcpServers": {
  174. "pacifica": {
  175. "command": "npx",
  176. "args": ["-y", "@pacifica-fi/mcp-server"],
  177. "env": {
  178. "ADDRESS": "<your Solana account address>",
  179. "AGENT_PRIVATE_KEY": "<your base58 agent wallet secret key>"
  180. }
  181. }
  182. }
  183. }
  184. ```
  185. ## Security
  186. - **Never commit or paste your `PRIVATE_KEY` or `AGENT_PRIVATE_KEY` anywhere public.**
  187. Treat any key that has been exposed as compromised and rotate it.
  188. - Prefer an **agent key** over your main key: it is revocable and limited in scope.
  189. - The config file holds your key in plaintext — protect it like any other secret.
  190. ## Development
  191. ```bash
  192. npm install # install dependencies
  193. npm run build # type-check + emit dist/
  194. npm run dev # run the server from source (tsx watch)
  195. npm test # type-check only (tsc --noEmit)
  196. npm run test:security # dependency compatibility and token address checks
  197. npm run gen:keys # generate 2 fresh keypairs (main + agent)
  198. npm run smoke:3a # live testnet smoke tests (read-only; signed suites need creds)
  199. npm run smoke:faucet # faucet tests (offline by default; live mint needs creds + flag)
  200. npm run smoke:deposit # deposit tests (offline by default; live deposit needs creds + flag)
  201. ```
  202. The published CLI includes `npm-shrinkwrap.json` so npm installs the tested dependency versions.
  203. Anchor and its dependencies are bundled to preserve the patched TOML parser selected by `overrides` in `package.json` when the CLI is installed as a dependency.
  204. After dependency changes, run `npm audit`, `npm run test:security`, and the offline faucet and deposit checks.
  205. Also install a packed copy in a temporary project and audit it before publishing.
  206. The `scripts/` directory contains live smoke tests against the Pacifica testnet
  207. (`npm run smoke:1a`, `smoke:agent`, etc.). Tests that need credentials are skipped
  208. unless `ADDRESS` / `PRIVATE_KEY` / `AGENT_PRIVATE_KEY` are set in the environment.
  209. `smoke:faucet` runs offline structural checks by default; its live-mint leg runs
  210. only with `SMOKE_FAUCET_MINT=1` and `PRIVATE_KEY` set (mints test USDP on devnet).
  211. `smoke:deposit` likewise runs offline by default; its live-deposit leg runs only
  212. with `SMOKE_DEPOSIT=1` and `PRIVATE_KEY` set.
  213. ### On-chain tools (faucet + deposit)
  214. Two tools act on Solana directly rather than through the REST API, so they need
  215. `PRIVATE_KEY` (an agent key cannot sign on-chain transactions) and use
  216. `SOLANA_RPC_URL` (defaults to public devnet; set a dedicated RPC to avoid rate
  217. limits):
  218. - **`mintUsdp`** — testnet only. Mints test USDP into the wallet's token account.
  219. - **`depositUsdp`** — moves the wallet's USDC/USDP into the exchange balance used
  220. for trading. Works on testnet and mainnet (selected by `PACIFICA_BASE_URL`). On
  221. **mainnet it moves real USDC** via the Pacifica mainnet program. The program id
  222. and collateral mint default per network and can be overridden with
  223. `PACIFICA_PROGRAM_ID` / `PACIFICA_USDC_MINT`. A typical testnet flow is
  224. `mintUsdp` then `depositUsdp`.
  225. ## License
  226. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.