Harvest MCP Server

Instructions

Args:
    project_id: The ID of the project to associate with the time entry
    task_id: The ID of the task to associate with the time entry
    spent_date: The date when the time was spent (YYYY-MM-DD)
    hours: The number of hours spent
    notes: Optional notes about the time entry

Implementation Reference

• harvest-mcp-server.py:114-139 (handler)

  The handler function decorated with @mcp.tool(), which registers the tool and defines its input schema via type hints and docstring. It creates a new time entry by sending a POST request to the Harvest API's time_entries endpoint using the shared harvest_request helper.

  @mcp.tool()
  async def create_time_entry(
      project_id: int, task_id: int, spent_date: str, hours: float, notes: str = None
  ):
      """Create a new time entry.
  
      Args:
          project_id: The ID of the project to associate with the time entry
          task_id: The ID of the task to associate with the time entry
          spent_date: The date when the time was spent (YYYY-MM-DD)
          hours: The number of hours spent
          notes: Optional notes about the time entry
      """
      params = {
          "project_id": project_id,
          "task_id": task_id,
          "spent_date": spent_date,
          "hours": hours,
      }
  
      if notes:
          params["notes"] = notes
  
      response = await harvest_request("time_entries", params, method="POST")
      return json.dumps(response, indent=2)

• harvest-mcp-server.py:21-43 (helper)

  Shared helper function used by create_time_entry (and other tools) to make authenticated HTTP requests to the Harvest API.

  async def harvest_request(path, params=None, method="GET"):
      headers = {
          "Harvest-Account-Id": HARVEST_ACCOUNT_ID,
          "Authorization": f"Bearer {HARVEST_API_KEY}",
          "User-Agent": "Harvest MCP Server",
          "Content-Type": "application/json",
      }
  
      url = f"https://api.harvestapp.com/v2/{path}"
  
      async with httpx.AsyncClient() as client:
          if method == "GET":
              response = await client.get(url, headers=headers, params=params)
          else:
              response = await client.request(method, url, headers=headers, json=params)
  
          if response.status_code != 200:
              raise Exception(
                  f"Harvest API Error: {response.status_code} {response.text}"
              )
  
          return response.json()