osmosis-agent-toolkit

The Osmosis Agent Toolkit MCP server exposes a set of capabilities for the Osmosis protocol that can be leveraged by language model assistants. By running the MCP server via npx, you enable a local or remote LLM agent to query protocol data, compose and sign transactions, and broadcast actions to Osmosis. The included toolkit pieces handle registry access, query construction, and the signing/broadcast workflow, so you can build conversational or autonomous agents that interact with Osmosis programmatically. To use it with Claude Desktop or Cursor, point your MCP configuration to the Osmosis entry and provide your mnemonic via the OSMOSIS_MNEMONIC environment variable.

Once running, the MCP server will respond to a range of context-providing and action-oriented requests such as querying pool data, simulating or proposing trades, and submitting signed transactions to the Osmosis chain. This enables LLM-driven strategies for liquidity provisioning, swaps, and governance-related actions within Osmosis, while abstracting away the low-level RPC details behind a stable MCP interface.

To integrate with your workflow, reference the Osmosis MCP server in your Claude Desktop or Cursor config as shown in the README example. Your agent can call the MCP endpoints to fetch on-chain data, prepare signed messages, and broadcast them, all while maintaining a concise, human-readable interaction with complex blockchain operations.

Prerequisites:

• Node.js (LTS version, 14+ recommended; 18+ preferred for modern tooling)
• Access to the internet to install packages via npx
• Optional: a secure mnemonic for Osmosis with appropriate safeguards

Installation steps:

1. Ensure Node.js is installed. Verify with:

node -v
npm -v

2. You can run the MCP server directly with npx (no global install required):

npx -y @osmosis-agent-toolkit/mcp

This will fetch the MCP package and start the server in your environment. If you prefer a persistent setup, you can install and run locally:

npm init -y
npm i @osmosis-agent-toolkit/mcp
# Then start as a script, e.g.:
node node_modules/@osmosis-agent-toolkit/mcp/dist/index.js

3. Configure environment variables for security and operation. In particular, set the mnemonic for Osmosis access:

export OSMOSIS_MNEMONIC="<your mnemonic here>"

4. If using Claude Desktop or Cursor, create the MCP config snippet and point your client to the Osmosis server entry as shown in the README. You can also store the config in a file (e.g., claude_desktop_config.json) and load it from your client.

Note: If you encounter issues with npx caching or package resolution, try clearing npm/yarn cache or running with a clean environment (e.g., a container or separate VM) to avoid conflicts with local dependencies.

Environment variables and configuration tips:

• OSMOSIS_MNEMONIC is required to sign and broadcast transactions. Treat it securely and avoid exposing it in logs or shared files.
• When running in shared environments, consider using a dedicated wallet/mnemonic and limiting permissions to the Kin OS checks.
• If you update the toolkit version, re-run the MCP server using the updated package to ensure compatibility.
• The MCP configuration uses the command-and-args pattern (npx with the package name). If you prefer local installs, you can adapt the command to node path usage after a local install.
• For debugging, you can run in verbose mode if supported by the package, and inspect any emitted MCP events or errors to fine-tune prompts and tool usage.