mcp-coda

# mcp-coda

[![PyPI version](https://img.shields.io/pypi/v/mcp-coda)](https://pypi.org/project/mcp-coda/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-coda)](https://pypi.org/project/mcp-coda/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-coda)](https://pypi.org/project/mcp-coda/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/vish288/mcp-coda/actions/workflows/tests.yml/badge.svg)](https://github.com/vish288/mcp-coda/actions/workflows/tests.yml)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)

<!-- mcp-name: io.github.vish288/mcp-coda -->

**Install:** `uvx mcp-coda` | [PyPI](https://pypi.org/project/mcp-coda/) | [MCP Registry](https://registry.modelcontextprotocol.io) | [Changelog](https://github.com/vish288/mcp-coda/releases)

**mcp-coda** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Coda](https://coda.io). It lets an AI assistant read and write Coda docs, pages, tables, and rows through the [Coda API](https://coda.io/developers/apis/v1). It also runs formulas, manages permissions and folders, publishes docs, and triggers automations. The server exposes **53 tools**, **12 resources**, and **5 prompts**. It supports the MCP 2026-07-28 specification (often called MCP 2.0) and stays compatible with 2025-11-25 clients. It works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

mcp-coda uses [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).

## 1-Click Installation

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://vish288.github.io/mcp-install?server=mcp-coda&install=cursor)

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-coda&install=vscode) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-coda&install=vscode-insiders)

> **Tip:** For other AI assistants (Claude Code, Windsurf, IntelliJ, Gemini CLI), visit the **[Coda MCP Installation Gateway](https://vish288.github.io/mcp-install?server=mcp-coda)**.

<details>
<summary><b>Manual Setup Guides (Click to expand)</b></summary>
<br/>

> Prerequisite: Install `uv` first (required for all `uvx` install flows). [Install uv](https://docs.astral.sh/uv/getting-started/installation/).

### Claude Code

```bash
claude mcp add coda -- uvx mcp-coda
```

### Windsurf & IntelliJ

**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
**IntelliJ:** Add to `Settings | Tools | MCP Servers`

> **Note:** The actual server config starts at `coda` inside the `mcpServers` object.

```json
{
  "mcpServers": {
    "coda": {
      "command": "uvx",
      "args": ["mcp-coda"],
      "env": {
        "CODA_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add -e CODA_API_TOKEN=your-token-here coda uvx mcp-coda
```

### pip / uv

```bash
uv pip install mcp-coda
```

</details>

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CODA_API_TOKEN` | **Yes** | - | Coda API token ([get one here](https://coda.io/account#apiSettings)) |
| `CODA_READ_ONLY` | No | `false` | Set to `true` to disable write operations |
| `CODA_BASE_URL` | No | `https://coda.io/apis/v1` | API base URL |
| `CODA_TIMEOUT` | No | `30` | Request timeout in seconds |

### Supported Token Types

The server checks these environment variables in order — first match wins:

1. `CODA_API_TOKEN`
2. `CODA_TOKEN`
3. `CODA_PAT`

Generate tokens at [coda.io/account#apiSettings](https://coda.io/account#apiSettings). Tokens grant access to all docs accessible by the token owner. Tokens have no scope restrictions. Coda's sharing settings control doc-level access.

## Compatibility

| Client | Supported | Install Method |
|--------|-----------|----------------|
| Claude Desktop | Yes | `claude_desktop_config.json` |
| Claude Code | Yes | `claude mcp add` |
| Cursor | Yes | One-click deeplink or `.cursor/mcp.json` |
| VS Code Copilot | Yes | One-click deeplink or `.vscode/mcp.json` |
| Windsurf | Yes | `~/.codeium/windsurf/mcp_config.json` |
| Any MCP client | Yes | stdio or HTTP transport |

## Protocol support

mcp-coda implements the **Model Context Protocol 2026-07-28** specification, often called MCP 2.0. It also stays compatible with **2025-11-25** clients. A FastMCP client pinned to 2026-07-28 and a legacy client both list all tools and reach the Coda API over stdio. The companion code PR adds a regression test that checks `tools/list` with an in-memory client pinned to 2026-07-28.

- **Spec version**: MCP 2026-07-28 (MCP 2.0), backward compatible with 2025-11-25.
- **Built on**: FastMCP 4.x and the MCP Python SDK 2.x.
- **Transports**: `stdio` (default) and `streamable-http` (recommended for remote). `sse` (HTTP+SSE) still works, but the 2026-07-28 specification deprecates it, so the server prints a warning.
- **Capabilities**: tools, resources, and prompts. The server uses no Roots, Sampling, Logging, elicitation, or resource subscriptions, so the 2026-07-28 deprecations do not affect it.

## Tools (53)

| Category | Count | Tools |
|----------|-------|-------|
| **Account** | 3 | whoami, resolve browser link, mutation status |
| **Docs** | 5 | list, get, create, update, delete |
| **Pages** | 8 | list, get, create, update, delete, get content, delete content, export |
| **Tables** | 4 | list tables, get table, list columns, get column |
| **Rows** | 7 | list, get, insert/upsert, update, delete, bulk delete, push button |
| **Permissions** | 6 | sharing metadata, list, add, delete, search principals, ACL settings |
| **Folders** | 5 | list, get, create, update, delete |
| **Misc** | 8 | formulas (list, get), controls (list, get), publishing (list categories, publish, unpublish), trigger automation |
| **Analytics** | 7 | doc analytics, doc summary, page analytics, pack analytics, pack summary, formula analytics, analytics updated |

<details>
<summary>Full tool reference (click to expand)</summary>

### Account
| Tool | Description |
|------|-------------|
| `coda_whoami` | Get current user info |
| `coda_resolve_browser_link` | Convert browser URL to API IDs |
| `coda_get_mutation_status` | Check async write status |

### Docs
| Tool | Description |
|------|-------------|
| `coda_list_docs` | List accessible docs |
| `coda_get_doc` | Get doc metadata |
| `coda_create_doc` | Create a new doc |
| `coda_update_doc` | Update doc title/icon |
| `coda_delete_doc` | Delete a doc |

### Pages
| Tool | Description |
|------|-------------|
| `coda_list_pages` | List pages in a doc |
| `coda_get_page` | Get page metadata |
| `coda_create_page` | Create a page |
| `coda_update_page` | Update page name/content |
| `coda_delete_page` | Delete a page |
| `coda_get_page_content` | Read page content |
| `coda_delete_page_content` | Clear page content |
| `coda_export_page` | Export page as HTML or markdown |

### Tables
| Tool | Description |
|------|-------------|
| `coda_list_tables` | List tables and views |
| `coda_get_table` | Get table metadata |
| `coda_list_columns` | List columns in a table |
| `coda_get_column` | Get column metadata |

### Rows
| Tool | Description |
|------|-------------|
| `coda_list_rows` | List and filter rows |
| `coda_get_row` | Get a single row |
| `coda_insert_rows` | Insert or upsert rows |
| `coda_update_row` | Update a row |
| `coda_delete_row` | Delete a row |
| `coda_delete_rows` | Bulk delete rows by filter |
| `coda_push_button` | Push a button column value |

### Formulas
| Tool | Description |
|------|-------------|
| `coda_list_formulas` | List named formulas |
| `coda_get_formula` | Get formula value |

### Controls
| Tool | Description |
|------|-------------|
| `coda_list_controls` | List controls |
| `coda_get_control` | Get control value |

### Permissions
| Tool | Description |
|------|-------------|
| `coda_get_sharing_metadata` | Get sharing config |
| `coda_list_permissions` | List ACL entries |
| `coda_add_permission` | Grant access |
| `coda_delete_permission` | Revoke access |
| `coda_search_principals` | Search users/groups |
| `coda_get_acl_settings` | Get ACL settings |

### Publishing
| Tool | Description |
|------|-------------|
| `coda_list_categories` | List publishing categories |
| `coda_publish_doc` | Publish a doc |
| `coda_unpublish_doc` | Unpublish a doc |

### Folders
| Tool | Description |
|------|-------------|
| `coda_list_folders` | List folders |
| `coda_get_folder` | Get folder details |
| `coda_create_folder` | Create a folder |
| `coda_update_folder` | Rename a folder |
| `coda_delete_folder` | Delete a folder |

### Automations
| Tool | Description |
|------|-------------|
| `coda_trigger_automation` | Trigger an automation rule |

### Analytics
| Tool | Description |
|------|-------------|
| `coda_list_doc_analytics` | Doc usage metrics |
| `coda_get_doc_analytics_summary` | Aggregated doc metrics |
| `coda_list_page_analytics` | Page usage metrics |
| `coda_list_pack_analytics` | Pack usage metrics |
| `coda_get_pack_analytics_summary` | Aggregated pack metrics |
| `coda_list_pack_formula_analytics` | Formula-level metrics |
| `coda_get_analytics_updated` | Analytics freshness timestamp |

</details>

## Resources (12)

The server exposes [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) that provide ambient context and do not consume tool calls.

### Data Resources (live API)

| URI | Name | Description |
|-----|------|-------------|
| `coda://docs` | Coda Docs | List of docs access