How to Configure the MCP Server for Claude Desktop or Cursor with Osmosis Agent Toolkit

Configure the MCP server by adding an Osmosis entry to your client's MCP configuration file, pointing the command to npx -y @osmosis-agent-toolkit/mcp and providing your OSMOSIS_MNEMONIC environment variable.

The osmosis-agent-toolkit repository provides a Model Context Protocol (MCP) server that exposes Osmosis blockchain operations—such as balance queries, swap quotes, and transaction broadcasting—to AI assistants. When you configure the MCP server for Claude Desktop or Cursor, you enable natural-language interaction with your Osmosis account through a secure, locally-running server process.

Architecture Overview

Understanding how the server components interact ensures you configure the correct parameters.

MCP Server Implementation

The entry point resides in packages/mcp/src/server.ts, where the OsmosisAgentServer class extends the MCP SDK's McpServer. According to the source code, the constructor instantiates OsmosisAgentToolkit using a mnemonic supplied either via the OSMOSIS_MNEMONIC environment variable or the --mnemonic CLI flag.

// packages/mcp/src/server.ts
export default class OsmosisAgentServer extends McpServer {
  private _toolkit: OsmosisAgentToolkit;
  
  constructor(mnemonic: string) {
    super({ name: 'Osmosis', version: '0.1.0' });
    this._toolkit = new OsmosisAgentToolkit(mnemonic);
    const accountTool = this._toolkit.accountTool;
    this.tool(accountTool.name, accountTool.description, () =>
      accountTool.call().then(createTextOutput),
    );
    // Additional tools registered similarly...
  }
}

Core Toolkit

The underlying functionality lives in packages/core/src/toolkit.ts, which exposes tools for account information, swap quotes, and transaction building. These tools return structured data that the MCP server serializes to JSON text via createTextOutput.

Installation and Prerequisites

You do not need to clone the repository to run the server. The package distributes an executable via npm.

Environment Setup

The server requires your Osmosis mnemonic to sign transactions and query account data. You have two options for providing this credential:

Option 1: Shell Environment Variable (Recommended)

export OSMOSIS_MNEMONIC="your twenty four word mnemonic phrase here gravity machine north sort system female filter attitude volume fold club stay"

Option 2: CLI Flag (Testing Only)

npx -y @osmosis-agent-toolkit/mcp --mnemonic='your mnemonic here'

Direct Execution

For manual testing without a client configuration, launch the server directly:

npx -y @osmosis-agent-toolkit/mcp

Configuring Claude Desktop and Cursor

Both Claude Desktop and Cursor read MCP server configurations from JSON files. When properly configured, these clients automatically launch the server process and expose Osmosis tools in the chat interface.

Claude Desktop Configuration

Create or edit the configuration file at ~/.config/claude_desktop_config.json (macOS/Linux) or the equivalent path on your system.

{
  "mcpServers": {
    "Osmosis": {
      "command": "npx",
      "args": [
        "-y",
        "@osmosis-agent-toolkit/mcp"
      ],
      "env": {
        "OSMOSIS_MNEMONIC": "gravity machine north sort system female filter attitude volume fold club stay"
      }
    }
  }
}

Security Note: Replace the placeholder mnemonic with your actual 24-word phrase. Alternatively, omit the env block and ensure OSMOSIS_MNEMONIC is exported in your shell environment before launching Claude Desktop.

Cursor Configuration

For Cursor, create a file named .cursor/mcp.json in your project root directory.

{
  "mcpServers": {
    "Osmosis": {
      "command": "npx",
      "args": [
        "-y",
        "@osmosis-agent-toolkit/mcp"
      ],
      "env": {
        "OSMOSIS_MNEMONIC": "<your mnemonic here>"
      }
    }
  }
}

Cursor automatically detects this file when you open the project. The server launches when you invoke an Osmosis-related command in the chat.

Environment Variable Management

For production use or shared environments, avoid hard-coding mnemonics in JSON files. Instead, use your shell's environment:

# Add to ~/.bashrc, ~/.zshrc, or equivalent

export OSMOSIS_MNEMONIC="your actual mnemonic here"

Then use a minimal configuration:

{
  "mcpServers": {
    "Osmosis": {
      "command": "npx",
      "args": ["-y", "@osmosis-agent-toolkit/mcp"],
      "env": {}
    }
  }
}

The server automatically picks up the OSMOSIS_MNEMONIC variable from the parent process environment.

Manual Server Startup and Debugging

When troubleshooting configuration issues, run the server manually with the MCP Inspector:

npx @modelcontextprotocol/inspector bun dist/index.js --mnemonic='your mnemonic here'

This launches a web interface where you can inspect tool schemas, test individual tool calls, and verify that your mnemonic correctly authenticates with the Osmosis blockchain.

Summary

• Install via npx: Use npx -y @osmosis-agent-toolkit/mcp to run the server without cloning the repository.
• Configure clients: Add the Osmosis MCP server to ~/.config/claude_desktop_config.json for Claude Desktop or .cursor/mcp.json for Cursor.
• Secure your mnemonic: Provide your OSMOSIS_MNEMONIC via environment variables rather than hard-coding in JSON files.
• Verify functionality: Use the MCP Inspector to debug connections and test tool execution before integrating with AI clients.

Frequently Asked Questions

Where does the MCP server store my Osmosis mnemonic?

The server does not persist your mnemonic to disk. According to the implementation in packages/mcp/src/server.ts, the mnemonic is passed directly to the OsmosisAgentToolkit constructor and held only in memory for the duration of the server process. Always ensure your configuration files have appropriate filesystem permissions if you choose to store the mnemonic in JSON configuration files.

Can I use the same MCP configuration for both Claude Desktop and Cursor?

Yes, the JSON structure is identical for both clients. However, the file location differs: Claude Desktop reads from ~/.config/claude_desktop_config.json (or your system's equivalent), while Cursor reads from .cursor/mcp.json in your project root. You can copy the mcpServers.Osmosis object between these files to use the same Osmosis account in both applications.

What happens if I don't provide the OSMOSIS_MNEMONIC environment variable?

The server will fail to start. The OsmosisAgentServer constructor in packages/mcp/src/server.ts requires a valid mnemonic string to instantiate the underlying toolkit. If you launch via npx without the --mnemonic flag and without the OSMOSIS_MNEMONIC environment variable set, the process will exit with an error indicating that authentication credentials are missing.

How do I verify that the MCP server is working correctly before adding it to my client configuration?

Use the MCP Inspector tool to test the server interactively. Run the command npx @modelcontextprotocol/inspector bun dist/index.js --mnemonic='your mnemonic here' to launch a web interface that lists all available Osmosis tools. You can execute individual tool calls—such as fetching account balances or generating swap quotes—to confirm that your mnemonic authenticates correctly and that the server returns valid JSON responses before integrating with Claude Desktop or Cursor.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}