Skip to content
Grain

Agent setup

Let your agent do it

Paste this into any agent that can run commands on your machine:

Fetch and follow the instructions at https://grain.tools/agent-setup.md to install Grain and connect it to my agents.

The agent reads the setup guide at grain.tools/agent-setup.md and then works through the setup in order:

  1. It installs Grain with the standard installer.
  2. It asks which of your AI agents you want to connect, and it connects only the ones you pick.
  3. It offers Grain’s built-in demo data and runs a few sample queries, so you can see results before you add your own database.

The sections below do the same thing by hand, one agent at a time.

Install Grain

Every agent below needs the grain command first.

# macOS and Linux
curl -fsSL https://grain.tools/install.sh | sh
# Windows (PowerShell)
irm https://grain.tools/install.ps1 | iex

The installer asks which agents to connect. You can skip that and use the commands below instead.

Claude Code

Connect it with one command:

grain connect --agent claude-code

This adds Grain to ~/.claude.json, so every Claude Code session on this computer has Grain’s tools. Restart Claude Code, then ask it to “show me the Grain demo data”.

To add it yourself, put this under mcpServers in ~/.claude.json:

{
  "mcpServers": {
    "grain": { "command": "grain", "args": ["--stdio"] }
  }
}

Codex

Connect it with one command:

grain connect --agent codex

This adds Grain to ~/.codex/config.toml. Start a new Codex session, then ask it to “show me the Grain demo data”.

To add it yourself, append this to ~/.codex/config.toml:

[mcp_servers.grain]
command = "grain"
args = ["--stdio"]

Cursor

Connect it with one command:

grain connect --agent cursor

This adds Grain to ~/.cursor/mcp.json. Restart Cursor and check that Grain is listed under Settings, MCP. Then ask the agent to “show me the Grain demo data”.

To add it yourself, put this in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "grain": { "command": "grain", "args": ["--stdio"] }
  }
}

Cursor also runs the Grain extension from Open VSX, which adds the results grid and saved connections inside the editor. See VS Code and compatible editors.

Other agents

grain connect --list prints every agent Grain supports and whether it found it on this computer: Claude Desktop, Claude Code, VS Code, Cursor, Windsurf and Codex. Claude Desktop does not read your shell PATH, so its config needs the full path, $HOME/.grain/bin/grain on macOS and Linux. grain disconnect removes Grain from every agent it connected.

Try the demo data

Grain ships with a small demo dataset about a bookstore, which runs on the built-in DuckDB database. Ask your agent to “show me the Grain demo data”, or run grain demo in a terminal. The demo needs no database server and no password.

What happens when your agent needs a database

An agent never needs to see your database password. When you ask an agent to add a database, it creates a draft connection and gives you a setup link, and you finish the connection in your browser. Connections and passwords explains the setup page.

Agents can only read until you say otherwise

MCP is on by default, so an agent can use Grain as soon as it’s connected. Safe mode is also on by default, so agents can only run read-only SQL until you change that setting. See Safe mode.

Documentation