|
| 1 | +# Quip MCP Server |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- Retrieve spreadsheet content from Quip documents |
| 8 | +- Support for selecting specific sheets by name |
| 9 | +- Returns data in CSV format |
| 10 | +- Handles authentication via Quip API token |
| 11 | +- Provides appropriate error messages for non-spreadsheet documents |
| 12 | + |
| 13 | +## Installation |
| 14 | + |
| 15 | +### Using uvx (recommended) |
| 16 | + |
| 17 | +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: |
| 18 | + |
| 19 | +```bash |
| 20 | +# Install uv if you don't have it |
| 21 | +curl -LsSf https://astral.sh/uv/install.sh | sh |
| 22 | + |
| 23 | +# Run the server directly with uvx |
| 24 | +uvx quip-mcp-server |
| 25 | +``` |
| 26 | + |
| 27 | +### Using pip |
| 28 | + |
| 29 | +Alternatively, you can install the package via pip: |
| 30 | + |
| 31 | +```bash |
| 32 | +pip install quip-mcp-server |
| 33 | +``` |
| 34 | + |
| 35 | +After installation, you can run it as a script: |
| 36 | + |
| 37 | +```bash |
| 38 | +python -m src.server |
| 39 | +``` |
| 40 | + |
| 41 | +### Set up environment variables |
| 42 | + |
| 43 | +Set up the required environment variables: |
| 44 | + |
| 45 | +```bash |
| 46 | +export QUIP_TOKEN=your_quip_api_token |
| 47 | +export QUIP_BASE_URL=https://platform.quip.com # Optional, defaults to this value |
| 48 | +``` |
| 49 | + |
| 50 | +Alternatively, create a `.env` file in the root directory: |
| 51 | +``` |
| 52 | +QUIP_TOKEN=your_quip_api_token |
| 53 | +QUIP_BASE_URL=https://platform.quip.com |
| 54 | +``` |
| 55 | + |
| 56 | +## Usage |
| 57 | + |
| 58 | +### Configure for Claude.app |
| 59 | + |
| 60 | +Add to your Claude settings: |
| 61 | + |
| 62 | +```json |
| 63 | +"mcpServers": { |
| 64 | + "quip": { |
| 65 | + "command": "uvx", |
| 66 | + "args": ["quip-mcp-server"], |
| 67 | + "env": { |
| 68 | + "QUIP_TOKEN": "your_quip_api_token" |
| 69 | + } |
| 70 | + } |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +### Running the Server Manually |
| 75 | + |
| 76 | +Run the server directly: |
| 77 | + |
| 78 | +```bash |
| 79 | +# Using uvx (recommended) |
| 80 | +uvx quip-mcp-server |
| 81 | + |
| 82 | +# Using python (if installed via pip) |
| 83 | +python -m src.server |
| 84 | +``` |
| 85 | + |
| 86 | +### Available Tools |
| 87 | + |
| 88 | +#### quip_read_spreadsheet |
| 89 | + |
| 90 | +Retrieves the content of a Quip spreadsheet as CSV. |
| 91 | + |
| 92 | +**Parameters:** |
| 93 | +- `threadId` (required): The Quip document thread ID |
| 94 | +- `sheetName` (optional): Name of the sheet to extract. If not provided, the first sheet will be used. |
| 95 | + |
| 96 | +**Example:** |
| 97 | +```json |
| 98 | +{ |
| 99 | + "threadId": "AbCdEfGhIjKl", |
| 100 | + "sheetName": "Sheet1" |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +**Response:** |
| 105 | +The tool returns the spreadsheet content in CSV format. |
| 106 | + |
| 107 | +**Error Handling:** |
| 108 | +- If the thread is not a spreadsheet, an error will be returned. |
| 109 | +- If the specified sheet is not found, an error will be returned. |
| 110 | + |
| 111 | +## How It Works |
| 112 | + |
| 113 | +The server uses two methods to extract spreadsheet data: |
| 114 | + |
| 115 | +1. **Primary Method**: Exports the spreadsheet to XLSX format using the Quip API, then converts it to CSV. |
| 116 | +2. **Fallback Method**: If the primary method fails, it parses the HTML content of the document to extract the table data. |
| 117 | + |
| 118 | +## Development |
| 119 | + |
| 120 | +### Project Structure |
| 121 | + |
| 122 | +``` |
| 123 | +quip-mcp-server/ |
| 124 | +├── src/ |
| 125 | +│ ├── __init__.py |
| 126 | +│ ├── server.py # Main MCP server implementation |
| 127 | +│ ├── quip_client.py # Quip API client |
| 128 | +│ └── tools.py # Tool definitions and handlers |
| 129 | +├── tests/ |
| 130 | +│ ├── __init__.py |
| 131 | +│ └── test_server.py # Unit tests for the server |
| 132 | +├── .uv/ |
| 133 | +│ └── config.toml # uv configuration settings |
| 134 | +├── pyproject.toml # Project metadata and dependencies (includes pytest config) |
| 135 | +├── uvproject.yaml # uv-specific project configuration |
| 136 | +├── uv.lock # Locked dependencies |
| 137 | +├── .python-version # Python version specification |
| 138 | +├── .env.example # Example environment variables |
| 139 | +├── LICENSE # MIT License |
| 140 | +└── README.md # Documentation |
| 141 | +``` |
| 142 | + |
| 143 | +### Development with uv |
| 144 | + |
| 145 | +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. |
| 146 | + |
| 147 | +#### Configuration Files |
| 148 | + |
| 149 | +- `pyproject.toml`: Standard Python packaging configuration |
| 150 | +- `uvproject.yaml`: uv-specific project configuration |
| 151 | +- `.uv/config.toml`: uv configuration settings |
| 152 | +- `.python-version`: Specifies Python 3.12 as the project's Python version (used by pyenv and other version managers) |
| 153 | + |
| 154 | +#### Setting Up a Development Environment |
| 155 | + |
| 156 | +To set up a development environment: |
| 157 | + |
| 158 | +```bash |
| 159 | +# Install uv if you don't have it |
| 160 | +curl -LsSf https://astral.sh/uv/install.sh | sh |
| 161 | + |
| 162 | +# Create a virtual environment and install dependencies |
| 163 | +uv venv |
| 164 | +uv pip install -e . |
| 165 | + |
| 166 | +# Install development dependencies |
| 167 | +uv pip install pytest black isort mypy |
| 168 | +``` |
| 169 | + |
| 170 | +Alternatively, you can use the uvproject.yaml file: |
| 171 | + |
| 172 | +```bash |
| 173 | +# Install dependencies from uvproject.yaml |
| 174 | +uv pip sync |
| 175 | +``` |
| 176 | + |
| 177 | +#### Running the Server with uv |
| 178 | + |
| 179 | +```bash |
| 180 | +# Using uvx (recommended for development) |
| 181 | +uvx quip-mcp-server |
| 182 | + |
| 183 | +# Or, if you're using a virtual environment: |
| 184 | +# Activate the virtual environment (if not auto-activated) |
| 185 | +source .venv/bin/activate |
| 186 | + |
| 187 | +# Run the server |
| 188 | +python -m src.server |
| 189 | +``` |
| 190 | + |
| 191 | +#### Running Tests |
| 192 | + |
| 193 | +The project uses pytest for testing. To run the tests: |
| 194 | + |
| 195 | +```bash |
| 196 | +# Install development dependencies |
| 197 | +uv pip install -e ".[dev]" |
| 198 | + |
| 199 | +# Run tests |
| 200 | +pytest |
| 201 | + |
| 202 | +# Run tests with coverage |
| 203 | +pytest --cov=src |
| 204 | +``` |
| 205 | + |
| 206 | +#### Debugging |
| 207 | + |
| 208 | +You can use the MCP inspector to debug the server: |
| 209 | + |
| 210 | +```bash |
| 211 | +# For uvx installations |
| 212 | +npx @modelcontextprotocol/inspector uvx quip-mcp-server |
| 213 | + |
| 214 | +# Or if you're developing locally |
| 215 | +cd /path/to/quip-mcp-server |
| 216 | +npx @modelcontextprotocol/inspector uv run src.server |
| 217 | +``` |
| 218 | + |
| 219 | +### Adding New Tools |
| 220 | + |
| 221 | +To add new tools: |
| 222 | + |
| 223 | +1. Define the tool in `src/tools.py` by adding it to the `get_quip_tools()` function. |
| 224 | +2. Implement the handler function for the tool. |
| 225 | +3. Register the handler in `src/server.py` by adding it to the `call_tool()` function. |
| 226 | + |
| 227 | +## License |
| 228 | + |
| 229 | +[MIT License](LICENSE) |
0 commit comments