Line Works MCP Server

A Model Context Protocol (MCP) server implementation for Line Works APIs (Calendar, Directory, User) with OAuth 2.0 authentication. This server allows you to interact with Line Works through natural language using MCP-compatible tools like Claude Desktop or Cursor.

Quick Start: See QUICKSTART.md for a 5-minute setup guide.

Features

• OAuth 2.0 Authentication: Secure authentication flow with token management
• Automatic Token Refresh: Handles token expiration and refresh automatically
• Calendar API: Full calendar and event management
• Directory API: Access user information and organization structure
• User API: Get user details by email or ID
• Natural Language Interface: Use with Claude Desktop or Cursor for conversational API access

Prerequisites

1. Line Works Developer Account and App Registration
2. Node.js 18+ installed
3. MCP-compatible client (Claude Desktop, Cursor, etc.)

Quick Start

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd lineworks-mcp-server

# Make sure you're in the project root directory
# You should see package.json, tsconfig.json, etc.
pwd  # Should show: /path/to/lineworks-mcp-server

# If setup.sh is in root directory, move it to scripts/
[ -f setup.sh ] && mv setup.sh scripts/

# Option 1: Use the automated setup script
npm run setup

# Option 2: Manual setup
npm install
cp .env.example .env
npm run build

# Validate your setup (optional but recommended)
npm run validate

2. Create Line Works App

1. Go to Line Works Developers Console
2. Create a new app or use existing one
3. Add OAuth 2.0 settings:
   • Redirect URI: http://localhost:3000/callback (⚠️ Must match EXACTLY)
   • Scopes: Select calendar, user, and directory scopes
4. Note down your Client ID and Client Secret

Important: Redirect URI Setup

• For local testing, use exactly: http://localhost:3000/callback
• No trailing slashes
• Use http not https for localhost
• If port 3000 is busy, you can change it:
  • Update redirect URI in Line Works console to new port
  • Set OAUTH_SERVER_PORT=8080 in your .env file
  • Update LINEWORKS_REDIRECT_URI to match

3. Configure Environment Variables

Create a .env file in the project root:

LINEWORKS_CLIENT_ID=your-client-id
LINEWORKS_CLIENT_SECRET=your-client-secret
LINEWORKS_REDIRECT_URI=http://localhost:3000/callback

4. Build the Server

npm run build

5. Configure MCP Client

For Claude Desktop

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lineworks-api": {
      "command": "node",
      "args": ["/path/to/lineworks-mcp-server/build/index.js"],
      "env": {
        "LINEWORKS_CLIENT_ID": "your-client-id",
        "LINEWORKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

For Cursor

Add to your Cursor settings:

{
  "mcp.servers": {
    "lineworks-api": {
      "command": "node",
      "args": ["/path/to/lineworks-mcp-server/build/index.js"],
      "env": {
        "LINEWORKS_CLIENT_ID": "your-client-id",
        "LINEWORKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Usage

First Time Authentication

1. Start your MCP client (Claude Desktop or Cursor)
2. Use the authenticate command:

   "Please authenticate with Line Works"

3. A browser window will open for OAuth authentication
4. Log in to Line Works and authorize the app
5. The token will be saved locally for future use

Available Commands

All commands can be used through natural language. Here are some examples:

User/Directory Management

"Get user info for [email protected]"
"Show me all users in the organization"
"List organization units"
"Show members of the sales department"

Calendar Management

"Show me all my calendars"
"Create a new calendar called 'Team Meetings' with color #FF5733"
"Update my 'Personal' calendar description"
"Delete the calendar with ID 'cal_123'"

Event Management

"Show me all events in my main calendar for this week"
"Create a meeting tomorrow at 2 PM for 1 hour titled 'Project Review'"
"Update the event 'Team Standup' to start at 10 AM instead"
"Delete the event with ID 'evt_456'"
"RSVP yes to the meeting invitation"

Note: When creating events, the data is automatically wrapped in the required eventComponents array format.

Free/Busy Check

"Check if [email protected] is free tomorrow from 2-3 PM"
"Find free time slots for [email protected] and [email protected] this week"

API Tools Reference

The server implements the following tools:

Authentication

1. authenticate - Initiate OAuth 2.0 authentication

Calendar APIs

2. get_user_default_calendar - Get user's default calendar
3. get_calendar_list - Get all calendars for a user
4. get_calendar - Get specific calendar details
5. create_calendar - Create a new calendar
6. update_calendar - Update calendar information
7. delete_calendar - Delete a calendar
8. get_event_list - Get events from a calendar
9. get_event - Get specific event details
10. create_event - Create a new event
11. update_event - Update event information
12. delete_event - Delete an event
13. respond_to_event - RSVP to an event invitation
14. get_freebusy - Check free/busy times for users

Directory/User APIs

15. get_user_by_email - Get user information by email address
16. get_user_by_id - Get user information by user ID
17. get_user_list - Get list of users in the organization
18. get_organization_units - Get list of organization units
19. get_org_unit_members - Get members of a specific organization unit

Project Structure

lineworks-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (generated)
├── .env                  # Environment variables (create this)
├── .lineworks_token.json # OAuth token storage (auto-generated)
├── package.json
├── tsconfig.json
└── README.md

Token Management

• Tokens are stored in .lineworks_token.json in the project root
• The server automatically refreshes expired tokens
• Delete this file to force re-authentication

Troubleshooting

Setup Issues

If you encounter issues during setup:

1. Verify you're in the correct directory:

   pwd  # Should show: /path/to/lineworks-mcp-server
   ls   # Should show: package.json, src/, README.md, etc.

2. Run the validation script:

   ./validate-setup.sh

3. Common issues:

   • Wrong directory: Always run from project root
   • Missing .env file: Copy from .env.example
   • Port in use: Change OAUTH_SERVER_PORT in .env
   • Build errors: Check Node.js version (18+ required)

Authentication Issues

1. Ensure your redirect URI matches exactly: http://localhost:3000/callback
2. Check that the calendar scope is enabled in your Line Works app
3. Verify CLIENT_ID and CLIENT_SECRET are correct

API Errors

1. Check the user ID format - it should be the Line Works user ID
2. Ensure you have proper permissions for the requested operation
3. Verify the calendar/event IDs are correct

MCP Connection Issues

1. Ensure the server path in your MCP client config is absolute
2. Check that Node.js is in your system PATH
3. Review the MCP client logs for detailed error messages

Security Notes

• Never commit .env or .lineworks_token.json files
• Keep your CLIENT_SECRET secure
• Use HTTPS in production environments
• Consider implementing additional security measures for production use

Development

Available Scripts

# Setup and validation
npm run setup      # Run initial setup
npm run validate   # Validate your setup
npm run help       # Show common commands

# Development
npm run dev        # Run in development mode with auto-reload
npm start          # Run production build
npm run build      # Build TypeScript to JavaScript

# Testing
tsx examples/test-calendar-operations.ts  # Run example test script

Project Structure

• [ ] Add support for recurring events
• [ ] Implement calendar sharing and permissions
• [ ] Add support for event attachments
• [ ] Implement webhook support for real-time updates
• [ ] Add multi-tenant support for hosted deployment

Contributing

Contributions are welcome! Please submit pull requests with:

• Clear description of changes
• Updated documentation
• Test coverage for new features

License

MIT License - see LICENSE file for details