{"id":30878422,"url":"https://github.com/zxkane/quip-mcp-server-python","last_synced_at":"2025-09-08T05:09:34.091Z","repository":{"id":286850380,"uuid":"962524207","full_name":"zxkane/quip-mcp-server-python","owner":"zxkane","description":"Model Context Procotol(MCP) server for fetching Quip document","archived":false,"fork":false,"pushed_at":"2025-06-04T03:24:47.000Z","size":47,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-04T10:21:00.900Z","etag":null,"topics":["mcp-server","mcp-server-python","mcp-server-stdio","model-context-protocol","model-context-protocol-servers","quip"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zxkane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-08T09:30:41.000Z","updated_at":"2025-06-04T03:24:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"2a68d454-3a61-4c56-acbd-90d407125b95","html_url":"https://github.com/zxkane/quip-mcp-server-python","commit_stats":null,"previous_names":["zxkane/quip-mcp-server","zxkane/quip-mcp-server-python"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zxkane/quip-mcp-server-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxkane%2Fquip-mcp-server-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxkane%2Fquip-mcp-server-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxkane%2Fquip-mcp-server-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxkane%2Fquip-mcp-server-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zxkane","download_url":"https://codeload.github.com/zxkane/quip-mcp-server-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxkane%2Fquip-mcp-server-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274135710,"owners_count":25228209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp-server","mcp-server-python","mcp-server-stdio","model-context-protocol","model-context-protocol-servers","quip"],"created_at":"2025-09-08T05:09:31.648Z","updated_at":"2025-09-08T05:09:34.080Z","avatar_url":"https://github.com/zxkane.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"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)\n\nCheck out the [Quip MCP Server (TypeScript)](https://github.com/zxkane/quip-mcp-server-typescript) repository for both stdio and http transport supports.\n\n# Quip MCP Server\n\nA 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.\n\n## Features\n\n- Retrieve spreadsheet content from Quip documents\n- Support for selecting specific sheets by name\n- Returns data in CSV format with metadata\n- Handles authentication via Quip API token\n- Provides appropriate error messages for non-spreadsheet documents\n- Automatically handles large spreadsheets by truncating content when necessary\n- Stores spreadsheet content locally for efficient access\n- Provides resource URIs for accessing complete spreadsheet content\n\n## Installation\n\n### Using uvx (recommended)\n\nWhen 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:\n\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Run the server directly with uvx\nuvx quip-mcp-server\n```\n\n### Using pip\n\nAlternatively, you can install the package via pip:\n\n```bash\npip install quip-mcp-server\n```\n\nAfter installation, you can run it as a script:\n\n```bash\npython -m src.server\n```\n\n### Set up environment variables\n\nSet up the required environment variables:\n```bash\nexport QUIP_TOKEN=your_quip_api_token\nexport QUIP_BASE_URL=https://platform.quip.com  # Optional, defaults to this value\nexport QUIP_STORAGE_PATH=/path/to/storage       # Optional, defaults to ~/.quip-mcp-server/storage\n```\n```\n\nAlternatively, create a `.env` file in the root directory:\n```\nQUIP_TOKEN=your_quip_api_token\nQUIP_BASE_URL=https://platform.quip.com\nQUIP_STORAGE_PATH=/path/to/storage\n```\n\n## Usage\n\n### Configure for Claude.app\n\nAdd to your Claude settings:\n\n```json\n\"mcpServers\": {\n  \"quip\": {\n    \"command\": \"uvx\",\n    \"args\": [\"quip-mcp-server\", \"--storage-path\", \"/path/to/storage\"],\n    \"env\": {\n      \"QUIP_TOKEN\": \"your_quip_api_token\"\n    }\n  }\n}\n```\n\nIf you want to use the file protocol for resource URIs:\n\n```json\n\"mcpServers\": {\n  \"quip\": {\n    \"command\": \"uvx\",\n    \"args\": [\"quip-mcp-server\", \"--storage-path\", \"/path/to/storage\", \"--file-protocol\"],\n    \"env\": {\n      \"QUIP_TOKEN\": \"your_quip_api_token\"\n    }\n  }\n}\n```\n\n### Running the Server Manually\n\nRun the server directly:\n\n```bash\n# Using uvx (recommended)\nuvx quip-mcp-server --storage-path /path/to/storage\n\n# Using python (if installed via pip)\npython -m src.server --storage-path /path/to/storage\n\n# With file protocol for resource URIs\nuvx quip-mcp-server --storage-path /path/to/storage --file-protocol\n\n# With debug logging enabled\nuvx quip-mcp-server --storage-path /path/to/storage --debug\n```\n\n### Available Tools\n\n#### quip_read_spreadsheet\n\nRetrieves the content of a Quip spreadsheet as CSV.\n\n**Parameters:**\n- `threadId` (required): The Quip document thread ID\n- `sheetName` (optional): Name of the sheet to extract. If not provided, the first sheet will be used.\n\n**Example:**\n```json\n{\n  \"threadId\": \"AbCdEfGhIjKl\",\n  \"sheetName\": \"Sheet1\"\n}\n```\n\n**Response:**\nThe tool returns a JSON object containing:\n- `csv_content`: The spreadsheet content in CSV format (truncated if too large)\n- `metadata`: Additional information about the spreadsheet:\n  - `total_rows`: Total number of rows in the spreadsheet\n  - `total_size`: Total size of the CSV content in bytes\n  - `is_truncated`: Boolean indicating if the content was truncated\n  - `resource_uri`: URI to access the complete spreadsheet content\n\n**Example Response (default protocol):**\n```json\n{\n  \"csv_content\": \"header1,header2\\nvalue1,value2\\n...\",\n  \"metadata\": {\n    \"total_rows\": 1000,\n    \"total_size\": 52840,\n    \"is_truncated\": true,\n    \"resource_uri\": \"quip://AbCdEfGhIjKl?sheet=Sheet1\"\n  }\n}\n```\n\n**Example Response (with --file-protocol):**\n```json\n{\n  \"csv_content\": \"header1,header2\\nvalue1,value2\\n...\",\n  \"metadata\": {\n    \"total_rows\": 1000,\n    \"total_size\": 52840,\n    \"is_truncated\": true,\n    \"resource_uri\": \"file:///path/to/storage/AbCdEfGhIjKl-Sheet1.csv\"\n  }\n}\n```\n\n**Error Handling:**\n- If the thread is not a spreadsheet, an error will be returned.\n- If the specified sheet is not found, an error will be returned.\n\n### Resource URIs\n\nThe server provides resource URIs for accessing complete spreadsheet content. These URIs can be used with the MCP resource access mechanism.\n\nBy 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.\n\n#### Default Protocol (quip://)\n\n**URI Format:**\n```\nquip://{threadId}?sheet={sheetName}\n```\n\n**Example:**\n```\nquip://AbCdEfGhIjKl?sheet=Sheet1\n```\n\n#### File Protocol (with --file-protocol option)\n\n**URI Format:**\n```\nfile://{storage_path}/{threadId}-{sheetName}.csv\n```\n\n**Example:**\n```\nfile:///home/user/.quip-mcp-server/storage/AbCdEfGhIjKl-Sheet1.csv\n```\n\nWhen accessed, the resource returns the complete CSV content of the spreadsheet, regardless of size.\n\n## How It Works\n\nThe server uses two methods to extract spreadsheet data:\n\n1. **Primary Method**: Exports the spreadsheet to XLSX format using the Quip API, then converts it to CSV.\n2. **Fallback Method**: If the primary method fails, it parses the HTML content of the document to extract the table data.\n\nFor large spreadsheets, the server:\n1. Saves the complete CSV content to local storage\n2. Returns a truncated version (up to 10KB) with metadata\n3. Provides a resource URI for accessing the complete content\n\n### Command Line Arguments\n\nThe server supports the following command line arguments:\n\n- `--storage-path`: Path to store CSV files (defaults to QUIP_STORAGE_PATH environment variable or ~/.quip-mcp-server/storage)\n- `--file-protocol`: Use file protocol for resource URIs (instead of quip:// protocol)\n- `--debug`: Enable debug logging\n\n**Example:**\n```bash\nuvx quip-mcp-server --storage-path /path/to/storage\n```\n\n## Development\n\n### Project Structure\n\n```\nquip-mcp-server/\n├── src/\n│   ├── __init__.py\n│   ├── server.py       # Main MCP server implementation\n│   ├── quip_client.py  # Quip API client\n│   ├── tools.py        # Tool definitions and handlers\n│   └── storage.py      # Storage abstraction and implementations\n├── tests/\n│   ├── __init__.py\n│   ├── test_server.py  # Unit tests for the server\n│   ├── test_storage.py # Unit tests for the storage module\n│   └── e2e/            # End-to-end tests\n│       ├── __init__.py\n│       ├── conftest.py # Test fixtures for e2e tests\n│       └── test_quip_integration.py # Integration tests with Quip API\n├── .uv/\n│   └── config.toml     # uv configuration settings\n├── pyproject.toml      # Project metadata and dependencies (includes pytest config)\n├── uvproject.yaml      # uv-specific project configuration\n├── uv.lock             # Locked dependencies\n├── .python-version     # Python version specification\n├── .env.example        # Example environment variables\n├── LICENSE             # MIT License\n└── README.md           # Documentation\n```\n\n### Development with uv\n\nThis 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.\n\n#### Configuration Files\n\n- `pyproject.toml`: Standard Python packaging configuration\n- `uvproject.yaml`: uv-specific project configuration\n- `.uv/config.toml`: uv configuration settings\n- `.python-version`: Specifies Python 3.12 as the project's Python version (used by pyenv and other version managers)\n\n#### Setting Up a Development Environment\n\nTo set up a development environment:\n\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create a virtual environment and install dependencies\nuv venv\nuv pip install -e .\n\n# Install development dependencies\nuv pip install pytest black isort mypy\n```\n\nAlternatively, you can use the uvproject.yaml file:\n\n```bash\n# Install dependencies from uvproject.yaml\nuv pip sync\n```\n\n#### Running the Server with uv\n\n```bash\n# Using uvx (recommended for development)\nuvx quip-mcp-server\n\n# Or, if you're using a virtual environment:\n# Activate the virtual environment (if not auto-activated)\nsource .venv/bin/activate\n\n# Run the server\npython -m src.server\n```\n\n#### Running Tests\n\nThe project uses pytest for testing. To run the tests:\n```bash\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=src\n\n# Run only e2e tests\npytest tests/e2e\n\n# Run a specific e2e test\npytest tests/e2e/test_quip_integration.py::test_connection\n```\n\n### End-to-End (e2e) Testing\n\nThe project includes end-to-end tests that verify integration with the actual Quip API. To run these tests:\n\n1. Create a `.env.local` file in the project root with your test configuration:\n   ```\n   # Quip API token (required)\n   QUIP_TOKEN=your_actual_quip_token_here\n   \n   # Test configuration\n   TEST_THREAD_ID=your_test_spreadsheet_thread_id\n   TEST_SHEET_NAME=Sheet1  # Optional: specific sheet name to test\n   ```\n\n2. Run the e2e tests:\n   ```bash\n   # Run all e2e tests\n   pytest tests/e2e\n   \n   # Run with verbose output\n   pytest -v tests/e2e\n   ```\n\nNote: The e2e tests will be skipped automatically if `.env.local` is missing or if required environment variables are not set.\n```\n\n#### Debugging\n\nYou can use the MCP inspector to debug the server:\n\n```bash\n# For uvx installations\nnpx @modelcontextprotocol/inspector uvx quip-mcp-server\n\n# Or if you're developing locally\ncd /path/to/quip-mcp-server\nnpx @modelcontextprotocol/inspector uv run src.server\n```\n\n### Adding New Tools\n\nTo add new tools:\n\n1. Define the tool in `src/tools.py` by adding it to the `get_quip_tools()` function.\n2. Implement the handler function for the tool.\n3. Register the handler in `src/server.py` by adding it to the `call_tool()` function.\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzxkane%2Fquip-mcp-server-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzxkane%2Fquip-mcp-server-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzxkane%2Fquip-mcp-server-python/lists"}