Hubstaff MCP Server – A Production-Ready Implementation

What Is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect directly to external tools and services, turning them from passive text generators into active participants in real workflows. MCP servers act as the bridge between an AI client and the APIs they expose. With the growing ecosystem of MCP-compatible clients, having a well-built, production-ready MCP server opens the door to genuinely useful AI-driven automation.

Emyoli Hubstaff MCP Server: Open-Source MCP Integration for Hubstaff

The Emyoli Hubstaff MCP Server is an open-source MCP server built by Emyoli Technologies. The server exposes both read and selected write access to the Hubstaff API v2, making it possible to query time tracking data, manage projects and tasks, and create manual time entries. All through natural language interactions with an MCP-compatible AI client.

The project is released under the MIT license and is not affiliated with Hubstaff. It is the first release (v0.1.0, May 2026) of what is clearly designed to be a mature, maintainable tool rather than a quick prototype.

You can find the entire open source project as well as a description on setup and configuration in our GitHub repository here.

Who Can Benefit from the Hubstaff MCP Server?

Whether you are already a Hubstaff user or just exploring what MCP can do, this project has something to offer.

Hubstaff-powered teams and organisations can immediately benefit from natural language access to their time tracking data — querying activities, managing projects, and creating time entries through an AI assistant, without writing a single line of custom integration code.

Agencies and consultancies managing multiple client projects in Hubstaff can use this server as a foundation for AI-assisted reporting and project oversight, reducing the manual work of pulling data and generating summaries.

Developers building with MCP will find this project valuable as a reference implementation. It goes well beyond a tutorial example — dual transports, Docker deployment, automatic token rotation, session management, CI, and proper secrets handling are all here, in a real codebase, solving real problems. If you are building your own MCP server, this is the kind of project worth studying.

Technical leads and architects evaluating whether MCP fits their stack will find this a useful concrete example. Seeing the pattern applied against a well-known workforce management API makes the effort, the tradeoffs, and the possibilities much easier to reason about than any abstract specification document could.

How the MCP Server Repository Is Structured

The repository follows a clean, professional layout that separates concerns clearly:

src/ – the main TypeScript source code for the server
tests/ – unit test suite powered by Vitest
.github/workflows/ – CI pipeline configuration via GitHub Actions
Dockerfile and docker-compose.yml – full Docker support for both stdio and HTTP deployment modes
.env.example – a documented template for environment configuration
md and SECURITY.md – community and security guidelines, signalling that this project is built with collaborative maintenance in mind

The presence of a dedicated build configuration (tsconfig.build.json), a separate test config (vitest.config.ts), and a linting setup (eslint.config.js with typescript-eslint) all point to a codebase that treats developer experience as a first-class concern.

Technology Stack: TypeScript, Node.js, Docker & MCP SDK

The project is built primarily in TypeScript, with a small amount of JavaScript and Dockerfile code rounding it out. Key technologies include:

Node.js 20+ as the runtime
TypeScript with strict compilation settings and a separate build tsconfig
@modelcontextprotocol/sdk for implementing the MCP protocol (both stdio and Streamable HTTP transports)
Express for the HTTP server mode
Vitest for unit testing
ESLint with TypeScript-ESLint for code quality
Docker & Docker Compose for containerised deployment
GitHub Actions for continuous integration

Key Features of the Hubstaff MCP Server

Authentication

The server supports two authentication flows against the Hubstaff API:

Personal Access Tokens (PAT): the recommended path for most automation use cases. Hubstaff PATs behave as long-lived refresh tokens; the server automatically exchanges them for short-lived access tokens and handles rotation transparently.
OAuth Refresh Tokens: an alternative for scenarios where an OAuth code exchange has already been handled externally.

Stdio and Streamable HTTP

One of the more thoughtful design decisions in this project is the support for two distinct deployment modes:

Stdio transport: The server runs as a child process, communicating with the MCP client over standard input/output. This is the classic integration pattern for clients like Cursor and Claude Desktop that spawn the server locally.
Streamable HTTP transport: The server runs as a detached HTTP service (default port 3333), exposing /mcp for MCP clients and /health for readiness checks. This mode is ideal for Docker-based deployments, remote VMs, or any setup where a persistent server is preferable.

The project’s Docker Compose configuration handles both modes explicitly, with separate service profiles for each, a practical detail that avoids common confusion around stdio vs. TCP when containerising MCP servers.

Available Hubstaff API Tools Exposed via MCP

The server exposes a comprehensive set of 20 tools covering the most commonly needed Hubstaff operations:

Read operations
- Retrieve the authenticated user’s profile (hubstaff_whoami)
- List organisations, projects, members, teams, tasks, job sites
- Query activities (both detailed and daily aggregated views)
- Access timesheets and screenshots
- Fetch individual user details
- A guardrailed generic GET escape hatch (hubstaff_api_get) restricted to organizations/* and users/* path prefixes for safe ad-hoc queries
Write operations
- Create and delete manual time entries
- Delete activity segments
- Create and update projects
- Create tasks

Destructive operations are explicitly labeled in their tool descriptions, which is a sensible safety practice when these tools will be called by an AI agent.

HTTP Session Management and Resilience

The HTTP transport includes several thoughtful session-management behaviours worth highlighting:

Sessions are held in memory; restarting the container clears them, but the server accepts a new initialize call even with a stale session ID, gracefully closing any previous sessions.
A single-session fallback is enabled by default: if only one active session exists, requests with a missing or stale session header are automatically routed to it — eliminating the common “No valid session ID provided” error when clients drop or cache the wrong header.
For stricter multi-client scenarios, this fallback can be disabled with MCP_HTTP_STRICT_SESSIONS=1.
By default, POST responses to /mcp return JSON rather than SSE-wrapped responses, which aligns with Cursor’s Streamable HTTP client and prevents session loss after the first round-trip.

Environment-Based Configuration

All configuration is handled through environment variables, making the server straightforward to integrate into any deployment environment. The full set of variables is documented in the README, covering token credentials, API base URL overrides, transport mode selection, and HTTP binding options. Critically, the Dockerfile is designed so that .env files are never baked into the image: credentials are injected at runtime via Docker Compose, which is the correct practice for secrets management.

A Production-Ready Foundation for Hubstaff and MCP

The Emyoli Hubstaff MCP Sever is a well-considered, production-oriented MCP server that goes beyond a minimal implementation. The dual transport modes, careful secrets management, thoughtful session handling, comprehensive tool coverage and solid developer tooling all reflect the kind of engineering discipline you’d want from a component living in an agentic workflow.

For teams looking to bring Hubstaff data into their AI-assisted workflows, this is a strong foundation. The project is open source and available at github.com/evirachmi/emyoli-mcp-hubstaff.