Check out the Quip MCP Server (TypeScript) repository for both stdio and http transport supports.

Quip MCP Server

A Model Context Protocol (MCP) server for interacting with Quip spreadsheets. This server provides tools to read spreadsheet data from Quip documents and return the content in CSV format.

Features

• Retrieve spreadsheet content from Quip documents
• Support for selecting specific sheets by name
• Returns data in CSV format with metadata
• Handles authentication via Quip API token
• Provides appropriate error messages for non-spreadsheet documents
• Automatically handles large spreadsheets by truncating content when necessary
• Stores spreadsheet content locally for efficient access
• Provides resource URIs for accessing complete spreadsheet content

Installation

Using uvx (recommended)

When using [uv](https://docs.astral.sh/uv/), no specific installation is needed. We will use [uvx](https://docs.astral.sh/uv/guides/tools/) to directly run the server:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the server directly with uvx
uvx quip-mcp-server

Using pip

Alternatively, you can install the package via pip:

pip install quip-mcp-server

After installation, you can run it as a script:

python -m src.server

Set up environment variables

Set up the required environment variables:

export QUIP_TOKEN=your_quip_api_token
export QUIP_BASE_URL=https://platform.quip.com  # Optional, defaults to this value
export QUIP_STORAGE_PATH=/path/to/storage       # Optional, defaults to ~/.quip-mcp-server/storage

Alternatively, create a `.env` file in the root directory:

QUIP_TOKEN=your_quip_api_token

QUIP_BASE_URL=https://platform.quip.com

QUIP_STORAGE_PATH=/path/to/storage

## Usage

### Configure for Claude.app

Add to your Claude settings:

"mcpServers": {

"quip": {

"command": "uvx",

"args": ["quip-mcp-server", "--storage-path", "/path/to/storage"],

"env": {

"QUIP_TOKEN": "your_quip_api_token"

}

}

}

If you want to use the file protocol for resource URIs:

"mcpServers": {

"quip": {

"command": "uvx",

"args": ["quip-mcp-server", "--storage-path", "/path/to/storage", "--file-protocol"],

"env": {

"QUIP_TOKEN": "your_quip_api_token"

}

}

}

### Running the Server Manually

Run the server directly:

Using uvx (recommended)

uvx quip-mcp-server --storage-path /path/to/storage

Using python (if installed via pip)

python -m src.server --storage-path /path/to/storage

With file protocol for resource URIs

uvx quip-mcp-server --storage-path /path/to/storage --file-protocol

With debug logging enabled

uvx quip-mcp-server --storage-path /path/to/storage --debug

### Available Tools

#### quip_read_spreadsheet

Retrieves the content of a Quip spreadsheet as CSV.

**Parameters:**
- `threadId` (required): The Quip document thread ID
- `sheetName` (optional): Name of the sheet to extract. If not provided, the first sheet will be used.

**Example:**

{

"threadId": "AbCdEfGhIjKl",

"sheetName": "Sheet1"

}

**Response:**
The tool returns a JSON object containing:
- `csv_content`: The spreadsheet content in CSV format (truncated if too large)
- `metadata`: Additional information about the spreadsheet:
  - `total_rows`: Total number of rows in the spreadsheet
  - `total_size`: Total size of the CSV content in bytes
  - `is_truncated`: Boolean indicating if the content was truncated
  - `resource_uri`: URI to access the complete spreadsheet content

**Example Response (default protocol):**

{

"csv_content": "header1,header2\nvalue1,value2\n...",

"metadata": {

"total_rows": 1000,

"total_size": 52840,

"is_truncated": true,

"resource_uri": "quip://AbCdEfGhIjKl?sheet=Sheet1"

}

}

**Example Response (with --file-protocol):**

{

"csv_content": "header1,header2\nvalue1,value2\n...",

"metadata": {

"total_rows": 1000,

"total_size": 52840,

"is_truncated": true,

"resource_uri": "file:///path/to/storage/AbCdEfGhIjKl-Sheet1.csv"

}

}

**Error Handling:**
- If the thread is not a spreadsheet, an error will be returned.
- If the specified sheet is not found, an error will be returned.

### Resource URIs

The server provides resource URIs for accessing complete spreadsheet content. These URIs can be used with the MCP resource access mechanism.

By default, the server uses the `quip://` protocol for resource URIs. However, you can use the `--file-protocol` option to use the `file://` protocol instead, which points directly to the local CSV files.

#### Default Protocol (quip://)

**URI Format:**

quip://{threadId}?sheet={sheetName}

**Example:**

quip://AbCdEfGhIjKl?sheet=Sheet1

#### File Protocol (with --file-protocol option)

**URI Format:**

file://{storage_path}/{threadId}-{sheetName}.csv

**Example:**

file:///home/user/.quip-mcp-server/storage/AbCdEfGhIjKl-Sheet1.csv

When accessed, the resource returns the complete CSV content of the spreadsheet, regardless of size.

## How It Works

The server uses two methods to extract spreadsheet data:

1. **Primary Method**: Exports the spreadsheet to XLSX format using the Quip API, then converts it to CSV.
2. **Fallback Method**: If the primary method fails, it parses the HTML content of the document to extract the table data.

For large spreadsheets, the server:
1. Saves the complete CSV content to local storage
2. Returns a truncated version (up to 10KB) with metadata
3. Provides a resource URI for accessing the complete content

### Command Line Arguments

The server supports the following command line arguments:

- `--storage-path`: Path to store CSV files (defaults to QUIP_STORAGE_PATH environment variable or ~/.quip-mcp-server/storage)
- `--file-protocol`: Use file protocol for resource URIs (instead of quip:// protocol)
- `--debug`: Enable debug logging

**Example:**

uvx quip-mcp-server --storage-path /path/to/storage

## Development

### Project Structure

quip-mcp-server/

├── src/

│ ├── __init__.py

│ ├── server.py # Main MCP server implementation

│ ├── quip_client.py # Quip API client

│ ├── tools.py # Tool definitions and handlers

│ └── storage.py # Storage abstraction and implementations

├── tests/

│ ├── __init__.py

│ ├── test_server.py # Unit tests for the server

│ ├── test_storage.py # Unit tests for the storage module

│ └── e2e/ # End-to-end tests

│ ├── __init__.py

│ ├── conftest.py # Test fixtures for e2e tests

│ └── test_quip_integration.py # Integration tests with Quip API

├── .uv/

│ └── config.toml # uv configuration settings

├── pyproject.toml # Project metadata and dependencies (includes pytest config)

├── uvproject.yaml # uv-specific project configuration

├── uv.lock # Locked dependencies

├── .python-version # Python version specification

├── .env.example # Example environment variables

├── LICENSE # MIT License

└── README.md # Documentation

### Development with uv

This project uses [uv](https://github.com/astral-sh/uv) for dependency management. uv is a fast Python package installer and resolver that can replace pip and virtualenv.

#### Configuration Files

- `pyproject.toml`: Standard Python packaging configuration
- `uvproject.yaml`: uv-specific project configuration
- `.uv/config.toml`: uv configuration settings
- `.python-version`: Specifies Python 3.12 as the project's Python version (used by pyenv and other version managers)

#### Setting Up a Development Environment

To set up a development environment:

Install uv if you don't have it

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a virtual environment and install dependencies

uv venv

uv pip install -e .

Install development dependencies

uv pip install pytest black isort mypy

Alternatively, you can use the uvproject.yaml file:

Install dependencies from uvproject.yaml

uv pip sync

#### Running the Server with uv

Using uvx (recommended for development)

uvx quip-mcp-server

Or, if you're using a virtual environment:

Activate the virtual environment (if not auto-activated)

source .venv/bin/activate

Run the server

python -m src.server

#### Running Tests

The project uses pytest for testing. To run the tests:

Install development dependencies

uv pip install -e ".[dev]"

Run tests

pytest

Run tests with coverage

pytest --cov=src

Run only e2e tests

pytest tests/e2e

Run a specific e2e test

pytest tests/e2e/test_quip_integration.py::test_connection

### End-to-End (e2e) Testing

The project includes end-to-end tests that verify integration with the actual Quip API. To run these tests:

1. Create a `.env.local` file in the project root with your test configuration:

# Quip API token (required)

QUIP_TOKEN=your_actual_quip_token_here

# Test configuration

TEST_THREAD_ID=your_test_spreadsheet_thread_id

TEST_SHEET_NAME=Sheet1 # Optional: specific sheet name to test

2. Run the e2e tests:

# Run all e2e tests

pytest tests/e2e

# Run with verbose output

pytest -v tests/e2e

Note: The e2e tests will be skipped automatically if `.env.local` is missing or if required environment variables are not set.

Debugging

You can use the MCP inspector to debug the server:

# For uvx installations
npx @modelcontextprotocol/inspector uvx quip-mcp-server

# Or if you're developing locally
cd /path/to/quip-mcp-server
npx @modelcontextprotocol/inspector uv run src.server

Adding New Tools

To add new tools:

1. Define the tool in src/tools.py by adding it to the get_quip_tools() function.

2. Implement the handler function for the tool.

3. Register the handler in src/server.py by adding it to the call_tool() function.

License

MIT License