quip-mcp-server-python

quip-mcp-server-python

1
databasescloud_platforms

The Quip MCP Server is a tool for accessing and managing spreadsheet data from Quip documents using the Model Context Protocol (MCP). It supports retrieving data in CSV format, facilitates storage and retrieval via resource URIs, and integrates authentication through Quip API tokens.

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, no specific installation is needed. We will use uvx 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:

```json
"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 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:

```bash
# 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