Install InnerSheet

What the installer adds to your config

This is the entry the installer merges into mcpServers (on Linux it prints it instead). uv run reads the dependency list inside server.py, so there is no virtual environment to manage.

{
  "mcpServers": {
    "innersheet": {
      "command": "uv",
      "args": ["run", "/path/to/innersheet/server.py"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS": "/path/to/innersheet/client_secret.json"
      }
    }
  }
}

Google Cloud setup — the one step everyone does once

InnerSheet signs in to Google Sheets with your own account, so Google needs to know the app exists. It is free and needs no credit card. Budget five minutes the first time.

Newer consoles group the OAuth settings under Google Auth Platform (tabs Branding, Audience, Clients); older ones call it OAuth consent screen. Both names are given below.

1. Create a project

   Go to console.cloud.google.com, sign in with the Google account that owns your sheets, and create a new project. Any name works — innersheet is fine.

2. Enable the two APIs

   Open APIs & Services → Library and enable Google Sheets API and Google Drive API. Drive is only used to find spreadsheets by name. Skipping this gives the "API has not been used in project" error.

3. Configure the consent screen

   Open Google Auth Platform → Branding (older consoles: APIs & Services → OAuth consent screen). Set the app name (InnerSheet) and your email, choose audience External, and save. No logo or privacy policy is needed for personal use.

4. Decide who can sign in: publish, or add yourself as a test user

   A new app starts in Testing. Open Audience and pick one:

   Option	How	Trade-off
   Publish the app Recommended	Audience → Publish app → confirm In production.	Sign-in stays valid. You see a one-time “Google hasn't verified this app” screen — normal for a personal project, no verification needed.
   Stay in Testing	Audience → Test users → Add users → add the Gmail you will sign in with.	Google expires the sign-in every 7 days, so you re-sign weekly.

   Doing neither gives Error 403: access_denied. Staying in Testing explains a weekly invalid_grant.

5. Create a Desktop OAuth client

   Open Google Auth Platform → Clients → Create client (older consoles: Credentials → Create Credentials → OAuth client ID). Application type Desktop app — not “Web application”, which causes redirect_uri_mismatch. Download the JSON.

6. Save it next to the server

   Rename the file to client_secret.json and put it in your innersheet folder — that is the path the installer configured. Never commit it to git or share it; it is in the shipped .gitignore.

7. First run: sign in once

   The first time a tool runs, your browser opens a Google sign-in page. Sign in and accept the permissions. The token is cached at ~/.config/innersheet/token.json and refreshes itself.

   “Google hasn't verified this app”? Expected for a project you created: click Advanced, then Go to InnerSheet (unsafe).

Configuration reference

InnerSheet is configured with environment variables. Put them in the env block of your client's config (or -e KEY=value for claude mcp add), then restart the client.

Command-line flags

Example: read-only, two sheets only

"env": {
  "GOOGLE_OAUTH_CLIENT_SECRETS": "/path/to/innersheet/client_secret.json",
  "SHEETS_MCP_READ_ONLY": "1",
  "SHEETS_MCP_ALLOWED_SPREADSHEETS": "1AbCdEfGhIjK,1ZyXwVuTsRqP"
}

The spreadsheet ID is the part of the sheet's URL between /d/ and /edit. After switching read-only on or off, delete token.json once so Google issues a token with the matching permissions.

Manual install (no installer)

If you'd rather see every step, the manual path is short. You need Python 3.10 or newer.

# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# Windows (PowerShell)
py -3 -m venv .venv
.venv\Scripts\pip install -r requirements.txt

Per-client config files are on the AI Clients page.

Verify the connection

After restarting your AI client, run these checks in order. Stop at the first one that fails and look it up on the Troubleshooting page.

1. In a terminal: uv run /path/to/innersheet/server.py --version should print innersheet 2.0.0. If not, the problem is the install, not the client.
2. "List my spreadsheets" — the agent should answer with real sheet names. If it can't find any, the Google sign-in didn't complete.
3. "Read A1:D10 from <your sheet>" — confirm the values match what you see in the browser.
4. "Upsert today's row in my daily report, dry run only" — the agent should describe what it would write, without writing anything.