harvest time tracking mcp server

a typescript based mcp (model context protocol) server for harvest time tracking app enabling llm clients to interact with harvest account.

prerequisites

• bun runtime
• harvest account with api access
• api personal access token from harvest
• account id from harvest

more details on how to create a personal access token can be found in the harvest api documentation.

tools

1. get-company - get company information
   • inputs: none
   • output: returns company information(name, url, id and currency).
2. search-clients - searches for clients in harvest account
   • inputs:
     • name: string (optional) - the name of the client to search for.
     • isactive: boolean (optional) - filter clients by their active status.
   • output: returns a list of clients with ids and other details.
3. get-client - get client information
   • inputs:
     • clientid: string - the id of the client to retrieve.
   • output: returns detailed information about the specified client.
4. search-projects - searches for projects in harvest account
   • inputs:
     • name: string (optional) - the name of the project to search for.
     • clientid: string (optional) - the id of the client to filter projects by.
     • isactive: boolean (optional) - filter projects by their active status.
   • output: returns a list of projects with ids and other details.
5. get-project - get project information
   • inputs:
     • projectid: string - the id of the project to retrieve.
   • output: returns detailed information about the specified project.
6. list-users - lists all users in the harvest account
   • inputs: none
   • output: returns a list of users with ids and other details.
7. get-user - get user information
   • inputs:
     • userid: string - the id of the user to retrieve.
   • output: returns detailed information about the specified user.
8. list-project-users - list all project user assignments
   • inputs:
     • projectid: string - the id of the project to retrieve users for.
   • output: returns a list of users assigned to the specified project.
9. list-project-tasks - list all project task assignments
   • inputs:
     • projectid: string - the id of the project to retrieve tasks for.
   • output: returns a list of tasks assigned to the specified project. note: more tools coming soon.

usage

claude desktop

• open the claude desktop config file claude-desktop-config.json and set the following details under mcpservers.

  {
    "mcpservers": {
      "harvest": {
        "command": "npx",
        "args": [
          "@harvest/mcp-server-typescript",
          // or use the path to the local build
          // "path/to/local/build/dist/index.js"
        ],
        "env": {
          "harvest_account_id": "<harvest account id>",
          "harvest_access_token": "<harvest personal access token>",
          "harvest_base_url": "<harvest base url>"
        }
      }
    }
  }
  

cursor ide

• open the cursor ide config file ~/.cursor/mcp.json or <project-root>/.cursor/mcp.json and set the following details under mcpservers.

  {
    "mcpservers": {
      "harvest": {
        "command": "npx",
        "args": [
          "@harvest/mcp-server-typescript",
          // or use the path to the local build
          // "path/to/local/build/dist/index.js"
        ],
        "env": {
          "harvest_account_id": "<harvest account id>",
          "harvest_access_token": "<harvest personal access token>",
          "harvest_base_url": "<harvest base url>"
        }
      }
    }
  }
  

local installation and development

1. install dependencies:

   npm install
   

2. build the project:

   npm run build
   

this will create a dist directory containing the compiled javascript files.

3. to use the local development version of mcp server instead of the published version, you can run the server directly from the local build:

   npm run build
   

   modify the mcp server configuration file in any of the clients (claude, cursor)

    {
      "mcpservers": {
        "harvest": {
          "command": "node",
          "args": [
            "path/to/local/build/dist/index.js"
          ],
          "env": {
            "harvest_account_id": "<harvest account id>",
            "harvest_access_token": "<harvest personal access token>",
            "harvest_base_url": "<harvest base url>"
          }
        }
      }
    } 
   

4. restart the client application (claude, cursor) to apply the changes and test the latest changes without publishing a new version.