Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zxkane/quip-mcp-server-python

Model Context Procotol(MCP) server for fetching Quip document
https://github.com/zxkane/quip-mcp-server-python

mcp-server mcp-server-python mcp-server-stdio model-context-protocol model-context-protocol-servers quip

Last synced: 10 months ago
JSON representation

Model Context Procotol(MCP) server for fetching Quip document

Awesome Lists containing this project

README 

          
[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/zxkane-quip-mcp-server-python-badge.png)](https://mseep.ai/app/zxkane-quip-mcp-server-python)



Check out the [Quip MCP Server (TypeScript)](https://github.com/zxkane/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:



```bash

# 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:



```bash

pip install quip-mcp-server

```



After installation, you can run it as a script:



```bash

python -m src.server

```



### Set up environment variables



Set up the required environment variables:

```bash

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:



```json

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



```bash

# 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:**

```json

{

  "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):**

```json

{

  "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):**

```json

{

  "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:**

```bash

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:



```bash

# 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:



```bash

# Install dependencies from uvproject.yaml

uv pip sync

```



#### Running the Server with uv



```bash

# 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:

```bash

# 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:

   ```bash

   # 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



[MIT License](LICENSE)