# How to Configure the MCP Server for Claude Desktop or Cursor with Osmosis Agent Toolkit > Easily configure the MCP server for Claude Desktop or Cursor. Add an Osmosis entry to your client MCP config pointing to npx y osmosis agent toolkit mcp and set your OSMOSIS MNEMONIC env var. - Repository: [Jon Ator/osmosis-agent-toolkit](https://github.com/jonator/osmosis-agent-toolkit) - Tags: how-to-guide - Published: 2026-03-05 --- **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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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. ```typescript // 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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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)** ```bash 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)** ```bash npx -y @osmosis-agent-toolkit/mcp --mnemonic='your mnemonic here' ``` ### Direct Execution For manual testing without a client configuration, launch the server directly: ```bash 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. ```json { "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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/.cursor/mcp.json) in your project root directory. ```json { "mcpServers": { "Osmosis": { "command": "npx", "args": [ "-y", "@osmosis-agent-toolkit/mcp" ], "env": { "OSMOSIS_MNEMONIC": "" } } } } ``` 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: ```bash # Add to ~/.bashrc, ~/.zshrc, or equivalent export OSMOSIS_MNEMONIC="your actual mnemonic here" ``` Then use a minimal configuration: ```json { "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: ```bash 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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/.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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/.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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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.