Harvestr

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

Built with FastMCP for clean, 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

Security 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

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())

Available Tools

Users

Tool	Description
harvestr_list_users	List all users
harvestr_get_user	Retrieve a specific user by ID
harvestr_list_user_attribute_values	List attribute values for a user
harvestr_update_user_attribute_values	Update attribute values for a user

Companies

Tool	Description
harvestr_list_companies	List all companies (optional: filter by externalUid)
harvestr_create_company	Create a new company
harvestr_get_company	Retrieve a specific company by ID
harvestr_update_company	Update a company
harvestr_list_company_attribute_values	List attribute values for a company
harvestr_update_company_attribute_values	Update attribute values for a company

Components

Tool	Description
harvestr_list_components	List all components (optional: filter by parentId)
harvestr_get_component	Retrieve a specific component by ID

Discoveries

Tool	Description
harvestr_list_discoveries	List all discoveries (optional: filter by parentId, include fields)
harvestr_get_discovery	Retrieve a specific discovery by ID
harvestr_get_discovery_state	Get the current state of a discovery
harvestr_list_discovery_feedback	List all feedback for a discovery

Discovery States

Tool	Description
harvestr_list_discovery_states	List all discovery states
harvestr_get_discovery_state_by_id	Retrieve a specific discovery state by ID

Messages

Tool	Description
harvestr_list_messages	List all messages
harvestr_get_message	Retrieve a specific message by ID
harvestr_list_message_feedback	List all feedback for a message

Feedback

Tool	Description
harvestr_list_feedback	List all feedback (optional: filter by messageId, discoveryId)
harvestr_get_feedback	Retrieve a specific feedback by ID

Attributes

Tool	Description
harvestr_list_user_attributes	List all user attribute definitions
harvestr_list_company_attributes	List all company attribute definitions

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.