Connect Gemini CLI to Paper via MCP

Use natural language in your terminal to create designs in Paper via MCP.

Introduction

30 Second Summary

Designers and developers have always worked in separate tools, passing files back and forth. What if your terminal could talk directly to your design canvas and create layouts from plain English?

In this project, you will connect Gemini CLI (a free AI coding agent from Google) to Paper (a design tool) using the MCP protocol. By the end, you will create real design elements on a canvas using nothing but natural language in your terminal.

What You'll Build

A free agentic design workflow where your terminal reads and writes directly to Paper's design canvas through the Model Context Protocol.

By the end of this project, you'll have:

A working Gemini CLI installation authenticated with your Google account.
A configured MCP connection between Gemini CLI and Paper that persists across sessions.
Design elements in Paper Desktop created entirely through natural language prompts in your terminal.
Secret Mission: Design a complete hero section for a landing page entirely through Gemini CLI prompts.

Are there any prerequisites?

You need a Mac running macOS, a Google account, and an internet connection. No prior experience with AI tools or design software is required.

Install Homebrew, Node.js, and Gemini CLI

To connect an AI agent to a design tool, you first need the agent itself installed on your Mac.

In this step, you will install three tools: Homebrew (a package manager for macOS), Node.js (a JavaScript runtime that Gemini CLI depends on), and Gemini CLI (Google's AI agent for your terminal). You will also authenticate Gemini CLI with your Google account.

In this step, get ready to:

Install Homebrew and Node.js on your Mac.
Install Gemini CLI and confirm it works.
Authenticate Gemini CLI with your Google account.

Install Homebrew and Node.js

Homebrew is a package manager that makes it easy to install developer tools on macOS. Node.js is a JavaScript runtime that Gemini CLI needs to run.

Open your terminal by pressing Cmd+Space to open Spotlight, typing Terminal, and pressing Enter.
Check if Homebrew is already installed by running this command:

brew --version

✔️ I see a version number

Homebrew is already installed. Skip ahead to the Node.js check below.

ⓧ Command not found

Install Homebrew by running this command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

What does this command do?

This downloads and runs Homebrew's official install script. The script will explain what it plans to do and pause for your confirmation before making any changes.

You may be prompted to enter your Mac's password. This is normal. Type it in and press Enter (the characters will not appear as you type).

Seeing an Xcode error?

If the installer asks you to install Command Line Tools for Xcode, allow it. This is a one-time setup that Homebrew needs.

help me fix a Homebrew installation error on macOS

Now check if Node.js is installed and meets the minimum version requirement. Gemini CLI requires Node.js 20.0.0 or higher.

Check your Node.js version by running:

node --version

✔️ I see version 20 or higher

Node.js is ready. Move on to the next substep.

ⓧ I see an older version

Your current Node.js version is below 20. Upgrade it through Homebrew.

Upgrade Node.js by running:

brew install node

This installs the latest Node.js version, which will be 20 or above. Run node --version again to confirm.

ⓧ Command not found

Node.js is not installed yet. Install it through Homebrew.

Install Node.js by running:

brew install node

Verify the installation by running:

node --version

You should see a version number starting with v20 or higher.

Still seeing command not found?

Close your terminal completely and reopen it. New installations sometimes require a fresh terminal session to update your PATH.

help me fix Node.js not being found after installing with Homebrew

Install Gemini CLI

Gemini CLI is Google's AI agent for the terminal. It can understand natural language prompts and use tools (via MCP) to interact with other applications.

Install Gemini CLI globally via Homebrew by running:

brew install gemini-cli

Verify the installation by running:

gemini --version

You should see a version number printed in your terminal. This confirms Gemini CLI is installed and accessible.

Command not found after installing?

Close your terminal and reopen it to refresh your PATH. If the issue persists, try the alternative install method:

npm install -g @google/gemini-cli

If gemini is still not found after the npm install, add the npm global bin directory to your PATH by running:

export PATH=$PATH:$(npm get prefix)/bin

Then add that same line to your ~/.zshrc so it persists across sessions.

help me get gemini CLI working on my Mac

Authenticate Gemini CLI with your Google account

Gemini CLI uses your Google account for authentication. This is free for personal use and does not require an API key.

Launch Gemini CLI by running:

gemini

When prompted "How would you like to authenticate for this project?", select Sign in with Google.
A browser window opens automatically. Sign in with your Google account and grant the requested permissions.
Return to your terminal after completing the sign-in. You should see a welcome message confirming Gemini CLI is ready.

Why no API key?

Gemini CLI authenticates through OAuth with your Google account. This gives you free access to Gemini models without needing to generate or manage an API key.

Browser didn't open?

If the browser did not open automatically, look in your terminal for a URL. Copy it and paste it into your browser manually to complete the sign-in.

help me authenticate Gemini CLI with my Google account

Your terminal is now powered by an AI agent. Next up, you will install Paper Desktop and connect it to Gemini CLI so the agent can create designs for you.

Install Paper Desktop and Start the MCP Server

Gemini CLI is installed and ready to go. Now you need the design tool it will connect to.

Paper is a design tool built on real HTML and CSS that AI agents can read and write directly. When you open a file in Paper Desktop, it automatically starts an MCP server in the background. This server is the bridge that lets Gemini CLI control the design canvas.

In this step, get ready to:

Download and install Paper Desktop.
Create a free Paper account.
Confirm the MCP server is running.

Download and install Paper Desktop

Paper Desktop is a native macOS application. You will download it directly from Paper's website and install it like any other Mac app.

Open your browser and go to paper.design/downloads.
Click the download button under Paper Desktop (version v0.4.2).
Once the download finishes, open the installer file.
Drag Paper into your Applications folder when prompted.
Press Cmd+Space to open Spotlight search.
Type Paper and press Enter to launch the app.
Click Sign Up to create a free Paper account.
Complete the sign-up form using your email or Google account.

What is Paper?

Paper is a design tool whose canvas is built on real HTML and CSS. This means AI agents can read and modify designs directly without needing to translate from a proprietary format.

The free tier includes 100 MCP tool calls per week, which is more than enough for this project.

macOS blocking the app?

If macOS shows a warning that the app is from an unidentified developer, go to System Settings > Privacy & Security and click Open Anyway.

Still stuck? Help me open Paper Desktop on my Mac

Create a new file to start the MCP server

Paper's MCP server starts automatically whenever you have a file open. No manual server setup is needed.

In Paper Desktop, click the button to create a new file.
You should see a blank canvas open in the app.

What just happened in the background?

The moment you opened a file, Paper started an MCP server at http://127.0.0.1:29979/mcp. This is the local URL that Gemini CLI will use to communicate with Paper in the next step.

You did not need to configure anything. Paper handles the server lifecycle automatically as long as a file is open.

Verify the MCP server is running

The MCP server only runs while Paper Desktop has a file open. If you close the file or quit the app, the server shuts down. Let's confirm everything is ready.

Confirm that Paper Desktop is showing your open file with a blank canvas visible.
Leave Paper Desktop open. Do not close the file or quit the app.

Keep Paper open for the rest of the project

The MCP server stops the moment you close your file or quit Paper Desktop. Keep the app running with your file open throughout the remaining steps. If Gemini CLI cannot connect to Paper later, this is the first thing to check.

Paper Desktop won't open or sign in?

Make sure you are connected to the internet. Paper requires an internet connection to sign in and sync files.

If you are on a corporate network with a VPN or proxy, you may need to allow *.paper.design in your network settings.

Help me troubleshoot Paper Desktop

Paper is installed and the MCP server is live. Next up, you will connect Gemini CLI to this server so the two tools can talk to each other.

Connect Gemini CLI to Paper's MCP Server

You have Gemini CLI authenticated and Paper's MCP server running in the background. Now you need to tell Gemini CLI where to find Paper so the two tools can communicate.

MCP (Model Context Protocol) is the bridge that lets an AI agent reach into external tools. By registering Paper's server URL with Gemini CLI, you give the agent permission to read and write to your design canvas.

In this step, get ready to:

Register Paper's MCP server with Gemini CLI at the user level.
Verify the connection shows as Connected.
Troubleshoot a Disconnected status if it appears.

Register Paper's MCP server with Gemini CLI

What is MCP?

MCP (Model Context Protocol) is a standard that defines how AI agents connect to external tools and services. Think of it like a USB port for AI. Any tool that speaks MCP can plug into any AI agent that supports it.

Paper exposes an MCP server on your machine. By registering that server with Gemini CLI, you let the agent discover Paper's available tools (creating shapes, adding text, arranging layouts) and call them on your behalf.

gemini mcp add --transport http paper http://127.0.0.1:29979/mcp -s user

What does this command do?

gemini mcp add registers a new MCP server with Gemini CLI.
--transport http tells Gemini to connect over HTTP, which is the protocol Paper's server uses.
paper is the friendly name you are giving this server. You will see it in the server list later.
http://127.0.0.1:29979/mcp is the local URL where Paper's MCP server is listening.
-s user saves the registration at the user level. This means it persists across all your projects and terminal sessions.

You should see no error output. The server is now registered in your Gemini CLI settings.

Seeing 'command not found'?

Make sure you are running the command in a fresh terminal tab (not inside an active Gemini CLI session). The gemini mcp add command runs outside the interactive session.

If gemini itself is not found, revisit Step 1 to confirm it installed correctly. Help me troubleshoot why gemini is not found in my terminal.

Verify the connection

Registering the server is one thing. You also need to confirm that Gemini CLI can actually reach Paper's MCP endpoint.

Start Gemini CLI by running:

gemini

Once the interactive session is running, type this command to check your MCP servers:

/mcp list

Look for a line that includes paper and http://127.0.0.1:29979/mcp (http) - Connected.

What should I see?

The output lists each registered MCP server with its name, URL, transport type, and connection status. A successful connection looks like:

✓ paper: http://127.0.0.1:29979/mcp (http) - Connected

You may also see a list of available tools that Paper exposes (for creating shapes, text, and layout elements). That confirms Gemini CLI has discovered Paper's capabilities.

Seeing 'Disconnected' instead?

This means Gemini CLI cannot reach Paper's MCP server. Here are the most common causes:

Paper Desktop must be open with a file loaded. The MCP server only runs while a file is open. Switch back to Paper and confirm you have a file open.
Run /mcp reload inside your Gemini CLI session to force it to reconnect.
If it still shows Disconnected, close Paper Desktop, reopen it with a file, then exit Gemini CLI with Ctrl+C and run gemini again to start a fresh session.

Help me debug why my Paper MCP server shows as Disconnected in Gemini CLI.

Your agentic pipeline is wired up. Next up, you will put it to the test by creating actual design elements in Paper using nothing but natural language prompts in your terminal.

Create Design Elements Through Natural Language

Your MCP connection is live and confirmed. Now comes the exciting part: you will use plain English in your terminal to create real design elements inside Paper.

Every prompt you type into Gemini CLI gets translated into tool calls against Paper's MCP server. The agent reads your intent, picks the right tools, and Paper renders the result on its canvas in real time.

In this step, get ready to:

Create a shape on the Paper canvas using a natural language prompt.
Add styled, positioned text through a more complex prompt.
Build a multi-element card layout with a single instruction.

Create your first design element with a prompt

The simplest way to test the connection is to ask Gemini CLI to create a single shape. This confirms the agent can communicate with Paper and produce visible output.

In your Gemini CLI session, type the following prompt and press Enter:

Create a red rectangle in Paper

What happens next?

Gemini CLI will ask you to approve the use of Paper's MCP tools before executing. You will see a confirmation prompt showing the server name and tool name, with options to allow or reject the action.

Select the option to allow all server tools for this session. This means you will not be asked again for each subsequent prompt in this session.

When the permission prompt appears, select Allow all server tools for this session.

Switch to Paper Desktop. You should see a red rectangle on your canvas.

Don't see a rectangle in Paper?

Make sure Paper Desktop still has your file open. The MCP server only runs while a file is active.
Check that you selected an allow option in the permission prompt (not reject).
If nothing appeared, try scrolling or zooming out on the Paper canvas. The element may have been placed outside your current viewport.

Still stuck? Why isn't my Gemini CLI prompt creating anything in Paper?

Add styled text above the rectangle

Now that you have a shape on the canvas, you can layer more elements on top. This time, you will give Gemini CLI positioning and styling instructions in the same prompt.

In Gemini CLI, type this prompt and press Enter:

Add a heading that says 'Welcome to My Site' with white text centered above the rectangle

Switch to Paper Desktop. You should see white heading text reading "Welcome to My Site" positioned above the red rectangle.

How does the agent know where to place it?

Gemini CLI reads the current state of your Paper canvas through MCP before placing new elements. When you say "above the rectangle", the agent identifies the existing rectangle and positions the text relative to it.

Text not appearing or in the wrong spot?

If the text did not appear at all, check that Paper Desktop is still in focus with your file open.
If the text is positioned incorrectly, try a follow-up prompt like "Move the heading to be centered directly above the red rectangle". The agent can adjust existing elements.

Need help? My text element isn't positioned correctly relative to other elements in Paper.

Build a multi-element card layout

For the final prompt, you will push the agentic workflow further by asking for a complex layout with repeating elements. This demonstrates how the agent breaks down a compound request into multiple design operations.

In Gemini CLI, type this prompt and press Enter:

Create a row of three cards, each with a colored circle and a label underneath

Switch to Paper Desktop. You should see three card elements arranged in a row, each containing a colored circle with a text label below it.

What is the agent doing behind the scenes?

For a prompt like this, the agent makes multiple MCP tool calls in sequence. It creates each card container, adds a circle with a unique color inside each one, then places a label underneath. All of these calls happen automatically from your single instruction.

Paper renders each element as it arrives, so you may see the canvas update incrementally rather than all at once.

Cards not looking right?

If only some cards appeared, the agent may have been interrupted. Try the prompt again or ask it to "finish creating the remaining cards".
If the layout is messy, try a follow-up prompt: "Align the three cards in a horizontal row with equal spacing". The agent can rearrange existing elements.

Still stuck? Help me get three evenly spaced cards in Paper through Gemini CLI.

Paper's free tier covers this project

Paper's free plan includes 100 MCP tool calls per week. Each prompt may use several calls, but you have plenty of headroom for experimentation.

Secret mission

Design a Complete Hero Section

You have created individual elements in Paper through Gemini CLI. Now, can you compose an entire landing page hero section using only natural language prompts? This challenge tests your ability to think in layers, iterate on design decisions, and direct an AI agent through a multi-element composition.

Clean Up Your Resources

This project runs entirely on your local machine using free tools and free-tier services. There are no ongoing costs from leaving things installed.

Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

Gemini CLI (installed via Homebrew).
MCP connection between Gemini CLI and Paper (registered at user scope).
Paper Desktop app (v0.4.2) with your design file.
Node.js (installed via Homebrew).
Gemini CLI configuration directory at ~/.gemini.

Keep everything running

No action needed. Choose this if you plan to keep using Gemini CLI with Paper for future design work.

Your MCP connection persists across sessions. Next time you open Paper and run gemini, the connection is ready.
Your Paper account and design files remain accessible through Paper Desktop.
Homebrew, Node.js, and Gemini CLI stay available for other projects.

Pause - I'll come back to this later

Quit running apps to free up memory. Your configuration and files stay intact for next time.

Quit Paper Desktop. This stops the MCP server automatically.
Close any open Gemini CLI sessions in your terminal.
Your MCP connection configuration stays saved. Next time you open Paper and launch Gemini CLI, it reconnects automatically.

Delete - I don't want to use this again

Remove all project resources from your machine. Follow each step below.

Remove the Paper MCP server from Gemini CLI by running:

gemini mcp remove paper -s user

Uninstall Gemini CLI by running:

brew uninstall gemini-cli

Remove the Gemini CLI configuration directory by running:

rm -rf ~/.gemini

Uninstall Node.js by running:

brew uninstall node

Delete Paper Desktop by dragging it from your Applications folder to the Trash.
Empty the Trash to complete removal.

Nice Work!

You just built a fully working agentic design pipeline. Your terminal now talks directly to a design tool, and you can create visual elements without ever touching the canvas yourself.

You've learned how to:

Installed and authenticated Gemini CLI on your Mac using Homebrew and Google OAuth.
Connected Gemini CLI to Paper Desktop via the MCP protocol using the httpUrl transport.
Created design elements in Paper using only natural language prompts typed into your terminal.
Secret Mission: Designed a complete hero section through iterative AI prompts, demonstrating the full design-to-code agentic workflow.

Ready to quiz yourself?