Content
[](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)
