Skip to content
Aptos Documentation

Setting up Aptos MCP with Claude Code
  1. Install Claude Code. The npm package still works:
Terminal window
npm install -g @anthropic-ai/claude-code

  1. Obtain your APTOS_BOT_KEY from Geomi (Bot Keys in the account menu). See Aptos MCP for the full steps.

  2. Navigate to your project:

Terminal window
cd your-awesome-project
  1. Add the Aptos MCP server with the Claude CLI. Put Claude’s own flags before the server name, and put the launch command after --:
Terminal window
claude mcp add --scope local --env APTOS_BOT_KEY=<your_bot_key> --transport stdio aptos-mcp -- npx -y @aptos-labs/aptos-mcp

Replace <your_bot_key> with the key from step 2.

--scope local stores the server for this project only. Use --scope user for every project on this machine, or --scope project to write a shareable .mcp.json (do not commit the Bot Key).

See the Claude Code MCP documentation for transport, scope, and --env syntax.

  1. Confirm the server is registered:
Terminal window
claude mcp list

You should see aptos-mcp in the list.

  1. Start Claude Code:
Terminal window
claude
  1. Prompt the agent with what aptos mcp version are you using? to verify the connection. It should report the currently published @aptos-labs/aptos-mcp version from the MCP Server Card.

Alternative: JSON configuration

Section titled “Alternative: JSON configuration”

If the CLI command fails, add the same stdio server as JSON:

Terminal window
claude mcp add-json aptos-mcp '{"command": "npx", "args": ["-y", "@aptos-labs/aptos-mcp"], "type": "stdio", "env": {"APTOS_BOT_KEY": "<your_bot_key>"}}'

Troubleshooting

Section titled “Troubleshooting”
  • Quit and restart Claude Code after changing MCP config so it reloads the server list.
  • Run claude mcp list if the Aptos tools do not appear.
  • Confirm APTOS_BOT_KEY is a valid Geomi Bot Key.