Harvestr MCP

🚀 Harvestr MCP Server

A Model Context Protocol (MCP) server for Harvestr.io, a product management platform for handling customer feedback, discoveries, and components.

Built with FastMCP for clean and Pythonic MCP development.

✨ Features

• Companies: List, create, update, and manage companies and their attributes.
• Components: Browse product components and their hierarchy.
• Discoveries: Access feature requests, bugs, and insights with state tracking.
• Feedback: Manage customer feedback linked to messages and discoveries.
• Messages: Access customer communications.
• Users: List users and manage their attributes.
• Attributes: Access custom field definitions for users and companies.

🚀 Quick Start

Prerequisites

• Python 3.10 or higher.
• uv (recommended) or pip.
• A Harvestr.io account with API access.

1. Clone and Install

# Clone the repository
git clone https://github.com/your-org/harvestr-mcp.git
cd harvestr-mcp

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

2. Get Your Harvestr API Token

1. Log in to your Harvestr.io account.
2. Navigate to Settings > Integrations > API Access Token.
3. Click Create new token and copy the generated token.

3. Configure the API Token

Set your API token as an environment variable:

# Linux/macOS
export HARVESTR_API_TOKEN="your-api-token-here"

# Windows (PowerShell)
$env:HARVESTR_API_TOKEN="your-api-token-here"

# Windows (CMD)
set HARVESTR_API_TOKEN=your-api-token-here

For persistent configuration, add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export HARVESTR_API_TOKEN="your-api-token-here"' >> ~/.bashrc
source ~/.bashrc

⚠️ Important Note

Treat your API token like a password. Never commit it to version control or share it publicly.

4. Run the Server

# Using FastMCP CLI (recommended)
fastmcp run src/harvestr_mcp/server.py:mcp

# Or using Python directly
python -m harvestr_mcp.server

5. Test with MCP Inspector (Optional)

To interactively test the server's tools:

npx @modelcontextprotocol/inspector fastmcp run src/harvestr_mcp/server.py:mcp

This opens a web interface where you can explore and test all available tools.

📦 Installation

Using uv (recommended)

uv pip install -e .

Using pip

pip install -e .

💻 Usage Examples

Running the Server

Stdio Transport (for local use with MCP clients)

# Using the FastMCP CLI
fastmcp run src/harvestr_mcp/server.py:mcp

# Or directly with Python
python -m harvestr_mcp.server

HTTP Transport (for remote access)

fastmcp run src/harvestr_mcp/server.py:mcp --transport http --port 8000

Using with Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on Linux/Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "harvestr": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/path/to/harvestr-mcp/src/harvestr_mcp/server.py:mcp"],
      "env": {
        "HARVESTR_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Using with FastMCP Client

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        # List all companies
        companies = await client.call_tool("harvestr_list_companies")
        print(companies)

        # Get a specific discovery
        discovery = await client.call_tool(
            "harvestr_get_discovery",
            {"discovery_id": "abc123", "include_fields": True}
        )
        print(discovery)

asyncio.run(main())

📚 Documentation

Available Tools

Users

Companies

Components

Discoveries

Discovery States

Messages

Feedback

Attributes

🔧 Technical Details

Development

Setting Up for Development

# Clone and enter the repository
git clone https://github.com/your-org/harvestr-mcp.git
cd harvestr-mcp

# Install with dev dependencies using uv (recommended)
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

Running Tests

The test suite uses pytest with pytest-asyncio for async test support:

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_client.py

# Run specific test class
pytest tests/test_server.py::TestUserTools

# Run with coverage (if installed)
pytest --cov=harvestr_mcp

Test Structure

tests/
├── __init__.py
├── conftest.py      # Shared fixtures and test configuration
├── test_client.py   # Tests for the Harvestr API client
├── test_types.py    # Tests for Pydantic models
└── test_server.py   # Tests for MCP server tools

Testing with MCP Inspector

For interactive testing of the server:

npx @modelcontextprotocol/inspector fastmcp run src/harvestr_mcp/server.py:mcp

Code Formatting

This project uses Ruff for linting and formatting:

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

API Documentation

For detailed API documentation, see the Harvestr API Docs.

📄 License

MIT License - see LICENSE for details.