# Coda MCP Server

A Model Context Protocol (MCP) server providing full access to the [Coda API v1](https://coda.io/developers/apis/v1). This enables AI coding agents like Claude to interact with Coda docs, tables, rows, formulas, and more.

## Features

- **51 tools** covering the complete Coda API surface
- Full CRUD operations on docs, pages, tables, and rows
- Formula and control access
- Permission and sharing management
- Publishing and folder operations
- Custom domain management
- Async operation tracking

## Quick Start

The easiest way to use this MCP server is via npx (no installation needed):

1. **Get your Coda API key** from [https://coda.io/account](https://coda.io/account) (Account Settings > API)

2. **Add to your Claude Desktop config:**
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "coda": {
      "command": "npx",
      "args": ["-y", "coda-io-mcp@latest"],
      "env": {
        "CODA_API_KEY": "your-coda-api-key"
      }
    }
  }
}
```

3. **Restart Claude Desktop** and start interacting with your Coda docs!

## Installation

### Option 1: npx (Recommended)

No installation needed! Just use the Quick Start configuration above. The `npx` command automatically downloads and runs the latest version from npm.

**Benefits:**
- No manual installation or path configuration
- Always uses the latest version with `@latest`
- Works the same on macOS, Windows, and Linux
- Automatic updates on Claude Desktop restart

### Option 2: Install from GitHub (For Development)

If you want to modify the code or contribute:

```bash
# Clone the repository
git clone https://github.com/bluestemso/coda-io-mcp.git
cd coda-io-mcp

# Install dependencies and build
npm install
```

The `prepare` script will automatically build the project after installation.

**Claude Desktop Configuration:**

```json
{
  "mcpServers": {
    "coda": {
      "command": "node",
      "args": ["/absolute/path/to/coda-io-mcp/build/index.js"],
      "env": {
        "CODA_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Replace `/absolute/path/to/coda-io-mcp` with the actual path where you cloned the repository.

### Option 3: Global npm Install

```bash
npm install -g coda-io-mcp@latest
```

**Claude Desktop Configuration:**

```json
{
  "mcpServers": {
    "coda": {
      "command": "coda-io-mcp",
      "env": {
        "CODA_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Important**: Replace `your-api-key-here` with your actual Coda API key in all configurations.

After adding the configuration, restart Claude Desktop to load the server.

## Prerequisites

- Node.js 18 or higher (required for all installation methods)
- A Coda API key from [https://coda.io/account](https://coda.io/account) (Account Settings > API)

## Usage

### With Claude Desktop

Once configured, you can use natural language with Claude to interact with your Coda docs. For example:

- "List all my Coda docs"
- "Create a new doc called 'Project Tracker'"
- "Add a row to the Tasks table with Status: 'In Progress'"
- "Get the value of the 'Total Revenue' formula"
- "Share the doc with user@example.com as editor"
- "Export the Requirements page as markdown"

### Standalone Testing

Run the server directly (requires `CODA_API_KEY` environment variable):

```bash
export CODA_API_KEY=your-api-key-here
node build/index.js
```

### With MCP Inspector

Test the server with the MCP Inspector:

```bash
export CODA_API_KEY=your-api-key-here
npx @modelcontextprotocol/inspector node build/index.js
```

## Available Tools

### Account (1 tool)
- `coda_whoami` - Get authenticated user info

### Docs (5 tools)
- `coda_list_docs` - List accessible docs
- `coda_create_doc` - Create new doc
- `coda_get_doc` - Get doc metadata
- `coda_update_doc` - Update doc title
- `coda_delete_doc` - Delete a doc

### Pages (9 tools)
- `coda_list_pages` - List pages in a doc
- `coda_create_page` - Create a new page
- `coda_get_page` - Get page info
- `coda_update_page` - Update page
- `coda_delete_page` - Delete page
- `coda_list_page_content` - List page content
- `coda_delete_page_content` - Delete page content
- `coda_export_page` - Start page export
- `coda_get_export_status` - Check export status

### Tables (2 tools)
- `coda_list_tables` - List tables and views
- `coda_get_table` - Get table info

### Columns (2 tools)
- `coda_list_columns` - List columns in a table
- `coda_get_column` - Get column info

### Rows (7 tools)
- `coda_list_rows` - List rows with filtering
- `coda_upsert_rows` - Insert or update rows
- `coda_delete_rows` - Bulk delete rows
- `coda_get_row` - Get single row
- `coda_update_row` - Update row
- `coda_delete_row` - Delete row
- `coda_push_button` - Push a button

### Formulas (2 tools)
- `coda_list_formulas` - List formulas
- `coda_get_formula` - Get formula value

### Controls (2 tools)
- `coda_list_controls` - List controls
- `coda_get_control` - Get control value

### Permissions (7 tools)
- `coda_get_sharing_metadata` - Get sharing info
- `coda_list_permissions` - List permissions
- `coda_add_permission` - Add permission
- `coda_delete_permission` - Remove permission
- `coda_search_principals` - Search users/groups
- `coda_get_acl_settings` - Get ACL settings
- `coda_update_acl_settings` - Update ACL settings

### Publishing (3 tools)
- `coda_list_categories` - List doc categories
- `coda_publish_doc` - Publish to gallery
- `coda_unpublish_doc` - Unpublish from gallery

### Folders (5 tools)
- `coda_list_folders` - List folders
- `coda_create_folder` - Create folder
- `coda_get_folder` - Get folder info
- `coda_update_folder` - Update folder
- `coda_delete_folder` - Delete folder

### Custom Domains (5 tools)
- `coda_list_domains` - List custom domains
- `coda_add_domain` - Add custom domain
- `coda_update_domain` - Update domain
- `coda_delete_domain` - Remove domain
- `coda_get_domain_provider` - Get DNS provider

### Mutations (1 tool)
- `coda_get_mutation_status` - Check async operation status

## Example Usage

Once configured with Claude Desktop, you can ask Claude to:

- "List all my Coda docs"
- "Create a new doc called 'Project Tracker'"
- "Add a row to the Tasks table with Status: 'In Progress'"
- "Get the value of the 'Total Revenue' formula"
- "Share the doc with user@example.com as editor"
- "Export the Requirements page as markdown"

## Troubleshooting

### Server not showing up in Claude Desktop

1. Make sure you've restarted Claude Desktop after adding the configuration
2. Check that the path to `build/index.js` is correct and absolute (not relative)
3. Verify your config file is valid JSON (use a JSON validator if needed)
4. Check Claude Desktop's logs for error messages

### "CODA_API_KEY is required" error

1. Make sure you've added the `env` section with `CODA_API_KEY` in your config
2. Verify your API key is correct (no extra spaces or quotes)
3. Ensure you've copied the key correctly from Coda

### Tools not working / API errors

1. Verify your Coda API key has the necessary permissions
2. Check that you have access to the docs/tables you're trying to access
3. Some operations require specific permission levels in Coda

### Finding Your Installation Path

If you cloned the repository and need to find the absolute path:

```bash
cd coda-io-mcp
pwd
```

This will output the full path (e.g., `/Users/yourname/projects/coda-io-mcp`). Use this path + `/build/index.js` in your config.

## Development

For contributors who want to modify or extend the server:

```bash
# Clone the repository
git clone https://github.com/bluestemso/coda-io-mcp.git
cd coda-io-mcp

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development (auto-rebuild on changes)
npm run watch
```

### Project Structure

- `src/index.ts` - MCP server entry point
- `src/coda-client.ts` - HTTP client for Coda API
- `src/tools/` - Individual tool implementations (13 modules, 51 tools total)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## Support

- **Issues**: [GitHub Issues](https://github.com/bluestemso/coda-io-mcp/issues)
- **Coda API Documentation**: [https://coda.io/developers/apis/v1](https://coda.io/developers/apis/v1)
- **MCP Documentation**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)

## License

MIT