Getting Started¶

This guide will help you install, configure, and run the EARLY MCP Server in just a few minutes.

Prerequisites¶

Before you begin, ensure you have:

• Node.js >= 18.0.0 (Download here)
• npm or yarn package manager
• EARLY Account with API access (Sign up)
• Git for cloning the repository

Installation¶

1. Clone the Repository¶

git clone https://github.com/janfincke/early-mcp-server.git
cd early-mcp-server

2. Install Dependencies¶

npm install

3. Build the Project¶

npm run build

Configuration¶

1. Get Your EARLY API Credentials¶

1. Open the EARLY app on your device
2. Go to Settings → Developer → API Keys
3. Generate a new API key and secret pair
4. Copy both the API Key and API Secret

2. Configure Environment Variables¶

Create a .env file in the project root:

cp .env.example .env

Edit .env with your credentials:

# Required - Get these from EARLY app settings
EARLY_API_KEY=your-early-api-key-here
EARLY_API_SECRET=your-early-api-secret-here

Testing the Installation¶

Method 1: Quick Test¶

Test that the server starts and responds:

npm run start:env

This should start the server without errors. Use Ctrl+C to stop it.

Method 2: Run Unit Tests¶

Use the built-in test suite to verify MCP functionality:

npm test

Expected output:

MCP protocol initialization
Tool listing  
Resource listing
Basic tool execution

Method 3: Run Unit Tests¶

Execute the full test suite:

npm test

You should see 24 tests passing across 4 test files.

Verify API Connection¶

Test your EARLY API credentials by listing activities:

1. Start the server: npm run start:env
2. In another terminal, use the test client to call list_activities
3. You should see your EARLY activities listed

If you get authentication errors: - Verify your API credentials are correct - Ensure both API key AND secret are provided
- Check that credentials are from the same EARLY account

Development Commands¶

Once installed, you can use these commands:

npm run dev        # Watch mode TypeScript compilation
npm run build      # Production build
npm run start      # Run the compiled server
npm run start:env  # Run with environment setup

npm test           # Run Jest tests
npm run lint       # Run ESLint
npm run lint:fix   # Fix ESLint issues automatically

Project Structure¶

Understanding the project layout:

early-mcp-server/
├── src/                    # TypeScript source
│   ├── index.ts           # Main MCP server
│   ├── early-api-client.ts # EARLY API client
│   ├── types.ts           # Type definitions
│   ├── tool-types.ts      # Tool argument types  
│   ├── error-utils.ts     # Error handling utilities
│   ├── utils.ts           # Helper functions
│   └── handlers/          # Tool handler implementations
├── dist/                   # Compiled JavaScript
├── tests/                  # Jest unit tests  
├── docs/                   # Documentation (this site)
├── start.js               # Entry point with env loading
└── .env                   # Environment variables (create this)

Next Steps¶

Now that you have the server running:

1. Learn the Tools - Explore all 6 time tracking tools
2. Claude Desktop Integration - Set up integration with detailed guide
3. Advanced Usage - Real-world patterns and best practices
4. Troubleshooting - Common issues and solutions

Quick Start Checklist¶

• Node.js >= 18.0.0 installed
• Repository cloned and dependencies installed
• Project built successfully (npm run build)
• EARLY API credentials obtained
• .env file configured with credentials
• Server starts without errors (npm run start:env)
• Unit tests pass (npm test)

You're ready to start using the EARLY MCP Server!