Magnum MCP Server

The Magnum MCP Server is a Go-based implementation of the Model Context Protocol (MCP) that exposes the Magnum workspace management API as tools and resources. It provides AI assistants and applications with comprehensive access to time tracking, project management, team collaboration, and reporting features through a standardized interface.

Table of Contents

• Quick Start
• Installation
• Configuration
• Integration Examples
• Available Tools
• MCP Resources
• Development
• API Reference

Quick Start

1. Build the server:

   git clone <repository>
   cd magnum-mcp
   go mod tidy
   go build -o magnum-mcp-server
   

2. Configure API endpoint:

   export MAGNUM_API_BASE_URL="https://api.magnum.app/api"
   

3. Run the server:

   ./magnum-mcp-server
   

The server communicates via HTTP (default: http://localhost:8080/rpc) using the MCP protocol (JSON-RPC 2.0 over HTTP POST) and can be integrated with any MCP-compatible AI application or custom client.

Installation

Prerequisites

• Go 1.21 or later
• Access to a Magnum workspace

Build from Source

# Clone the repository
git clone <repository>
cd magnum-mcp

# Install dependencies
go mod tidy

# Build the server
go build -o magnum-mcp-server

# Verify installation
./magnum-mcp-server --help

Verify Installation

Test the server with a simple HTTP request:

curl -X POST -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  http://localhost:8080/rpc

Configuration

The server supports multiple configuration methods with the following priority:

1. Environment variables (highest priority)
2. Configuration file (magnum-mcp-config.json)
3. Default values (lowest priority)

Environment Variables

# Required
export MAGNUM_API_BASE_URL="https://api.magnum.app/api"

# Optional - Authentication (obtained via auth tools)
export MAGNUM_JWT_TOKEN="your_jwt_token"
export MAGNUM_REFRESH_TOKEN="your_refresh_token"

# Optional - Server Configuration
export MAGNUM_LOG_LEVEL="info"              # debug, info, warn, error
export MAGNUM_CONFIG_FILE="./config.json"   # Custom config file path
export MAGNUM_DEFAULT_WORKSPACE_ID="123"    # Default workspace for operations
export MAGNUM_HTTP_ADDR=":8080"             # HTTP listen address (default :8080)

Configuration File

Create magnum-mcp-config.json:

{
  "api_base_url": "https://api.magnum.app/api",
  "jwt_token": "",
  "refresh_token": "",
  "default_workspace_id": 0,
  "timeout": "30s",
  "server_name": "magnum-mcp-server",
  "server_version": "1.0.0",
  "log_level": "info"
}

Note: Tokens are automatically managed by the server. Use the auth tool to authenticate, and tokens will be saved to the configuration file for persistence across sessions.

Integration Examples

Claude Desktop

Add the Magnum MCP Server to your Claude Desktop configuration:

macOS/Linux (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "magnum": {
      "command": "/path/to/magnum-mcp-server",
      "env": {
        "MAGNUM_API_BASE_URL": "https://api.magnum.app/api"
      }
    }
  }
}

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "magnum": {
      "command": "C:\\path\\to\\magnum-mcp-server.exe",
      "env": {
        "MAGNUM_API_BASE_URL": "https://api.magnum.app/api"
      }
    }
  }
}

After configuration, restart Claude Desktop. You'll see Magnum tools available in the interface and can start with:

"Please help me authenticate with Magnum using my email and password"

Note: If Claude Desktop or your MCP client supports HTTP MCP servers, you can point it to http://localhost:8080/rpc directly. Otherwise, use a compatible proxy or integration layer.

Gemini CLI

Install and configure the Gemini CLI with MCP support:

# Install Gemini CLI (if not already installed)
npm install -g @google-ai/generativelanguage

# Create MCP configuration file
mkdir -p ~/.config/gemini
cat > ~/.config/gemini/mcp_config.json << 'EOF'
{
  "servers": {
    "magnum": {
      "command": "/path/to/magnum-mcp-server",
      "env": {
        "MAGNUM_API_BASE_URL": "https://api.magnum.app/api"
      }
    }
  }
}
EOF

# Run Gemini with MCP support
gemini --mcp-config ~/.config/gemini/mcp_config.json

Example usage in Gemini CLI:

gemini> Use the magnum auth tool to log me in with email user@example.com
gemini> Show me my workspaces and then list all projects in the first workspace
gemini> Create a new time tracking activity for today from 9 AM to 5 PM for project "Website Development"

Open WebUI Integration (with MCP-to-OpenAPI Proxy)

Open WebUI recommends using the MCP-to-OpenAPI proxy server (mcpo) to expose your MCP server (like magnum-mcp-server) as a standard REST/OpenAPI service. This enables seamless integration with Open WebUI and any OpenAPI-compatible client.

Why use the MCP Proxy (mcpo)?

• Instant REST/OpenAPI endpoints for all your MCP tools—no protocol glue code needed.
• Interactive Swagger UI docs at /docs for every tool.
• Secure, scalable HTTP—no raw stdio or socket juggling.
• Cloud and local support—run your MCP server anywhere.

Quickstart: Run the Proxy Locally

1. Install mcpo (requires Python 3.8+):

   pip install mcpo uv
   

2. Start your MCP server via the proxy (replace with your actual command):

   uvx mcpo --port 8000 -- ./magnum-mcp-server
   

   • This launches magnum-mcp-server and exposes all its tools as REST endpoints at http://localhost:8000.
   • Interactive OpenAPI docs: http://localhost:8000/docs

3. Configure Open WebUI to use your new OpenAPI endpoint:

   • Go to Admin Settings → Connections → OpenAPI Servers in Open WebUI.
   • Add a new server with:
     • Name: magnum
     • Base URL: http://localhost:8000
     • (Optional) Set authentication or other options as needed.

4. Use your tools in Open WebUI!

   • All MCP tools are now available as REST endpoints and documented in Swagger UI.
   • You can also call them from any OpenAPI-compatible client, SDK, or script.

Docker Example

To deploy the proxy and your MCP server together:

FROM python:3.11-slim
WORKDIR /app
RUN pip install mcpo uv
COPY . .
CMD ["uvx", "mcpo", "--host", "0.0.0.0", "--port", "8000", "--", "./magnum-mcp-server"]

Then:

docker build -t magnum-mcp-proxy .
docker run -p 8000:8000 magnum-mcp-proxy

---

For more details and advanced deployment, see the Open WebUI MCP docs.

Custom Integration

For custom applications, communicate with the server via JSON-RPC 2.0 over HTTP POST:

import requests

class MagnumMCPClient:
    def __init__(self, url="http://localhost:8080/rpc"):
        self.url = url
        self._initialize()
    
    def _initialize(self):
        init_request = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "initialize",
            "params": {}
        }
        self._send_request(init_request)
    
    def _send_request(self, request):
        resp = requests.post(self.url, json=request)
        resp.raise_for_status()
        return resp.json()
    
    def authenticate(self, email, password):
        return self._send_request({
            "jsonrpc": "2.0",
            "id": 2,
            "method": "tools/call",
            "params": {
                "name": "auth",
                "arguments": {
                    "operation": "login",
                    "email": email,
                    "password": password
                }
            }
        })

# Usage
client = MagnumMCPClient()
result = client.authenticate('user@example.com', 'password')
print(result)

Available Tools

Authentication

• auth: Unified authentication tool supporting multiple operations:
  • operation: "login" - Email/password authentication
  • operation: "google_login" - Google OAuth authentication
  • operation: "refresh" - Refresh authentication token
  • operation: "status" - Check authentication status

Workspace Management

• workspace_list: Get user's accessible workspaces
• workspace_get: Get detailed workspace information
• workspace_create: Create new workspace

User Management

• workspace_users_list: List workspace employees with pagination
• workspace_user_get: Get specific user details
• workspace_users_lookup: Get user ID-name pairs for dropdowns

Activity Management

• activity_list: List activities with filtering and pagination
• activity_create: Create new time tracking activity
• activity_update: Update existing activity
• activity_delete: Delete activity

Project Management

• project_list: List workspace projects
• project_get: Get detailed project information
• project_create: Create new project
• project_update: Update existing project
• project_delete: Delete project

Reporting

• report_generate: Generate various reports and analytics
• report_export: Export data in different formats
• report_status: Check report generation status

MCP Resources

Access structured data through MCP resources:

• workspace://{workspace_id}: Workspace configuration and settings
• users://{workspace_id}: Employee directory
• activities://{workspace_id}: Activity logs and time tracking data
• projects://{workspace_id}: Project information and assignments
• reports://{workspace_id}: Available reports and export options

Development

Live Reload with Air

For rapid development with automatic rebuild and restart on code changes, use Air:

Install Air

• With Go 1.23+ (recommended):

  go install github.com/air-verse/air@latest
  

  Make sure $GOPATH/bin or $(go env GOPATH)/bin is in your PATH.

• Or via script:

  curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s
  

Usage

1. The repo includes a preconfigured .air.toml for this project.

2. Start the live-reloading server:

   air
   

   This will rebuild and restart the server on any code change.

3. To customize, edit .air.toml as needed (see Air docs).

---

Project Structure

magnum-mcp/
├── main.go                 # Application entry point
├── server/                 # MCP protocol implementation
│   ├── server.go          # Core MCP server with JSON-RPC
│   ├── resources.go       # MCP resource handlers
│   └── server_test.go     # Test suite
├── api/                   # Magnum API client
│   ├── client.go          # HTTP client with authentication
│   ├── types.go           # API data structures
│   └── endpoints.go       # API endpoint constants
├── config/                # Configuration management
│   └── config.go          # Environment and file-based config
├── common/                # Shared interfaces and utilities
│   └── interfaces.go      # Tool definitions and handlers
├── handlers/              # MCP tool implementations
│   ├── auth_v2.go         # Authentication operations
│   ├── workspace.go       # Workspace management
│   ├── users.go           # Employee directory
│   ├── activities.go      # Time tracking and activities
│   ├── projects.go        # Project management
│   └── reports.go         # Reporting and analytics
└── test_mcp.go           # MCP testing utilities

Building and Testing

# Build the server
go build -o magnum-mcp-server

# Run tests
go test ./...

# Run specific package tests
go test ./server/

# Run with verbose output
go test -v ./...

# Build for different platforms
GOOS=windows GOARCH=amd64 go build -o magnum-mcp-server.exe
GOOS=darwin GOARCH=amd64 go build -o magnum-mcp-server-darwin
GOOS=linux GOARCH=amd64 go build -o magnum-mcp-server-linux

Contributing

1. Follow Go conventions and use gofmt
2. Add tests for new functionality
3. Update documentation for API changes
4. Use descriptive commit messages

API Reference

Authentication Flow

// 1. Login with email/password
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "auth",
    "arguments": {
      "operation": "login",
      "email": "user@example.com",
      "password": "your_password"
    }
  }
}

// 2. Check authentication status
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "auth",
    "arguments": {
      "operation": "status"
    }
  }
}

Workspace Operations

// List workspaces
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "workspace_list",
    "arguments": {}
  }
}

// Get workspace details
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "workspace_get",
    "arguments": {
      "workspace_id": 123
    }
  }
}

Activity Management

// Create time tracking activity
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "activity_create",
    "arguments": {
      "workspace_id": 123,
      "type": "daily",
      "date": "2024-01-15",
      "start_time": "09:00",
      "end_time": "17:00",
      "description": "Development work",
      "project_id": 456
    }
  }
}

// List activities with filtering
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "activity_list",
    "arguments": {
      "workspace_id": 123,
      "start_date": "2024-01-01",
      "end_date": "2024-01-31",
      "user_id": 789,
      "page": 1,
      "limit": 20
    }
  }
}

Resource Access

// Read workspace resource
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "resources/read",
  "params": {
    "uri": "workspace://123"
  }
}

// List available resources
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "resources/list",
  "params": {}
}

Error Handling

The server provides comprehensive error handling with detailed messages:

• Authentication errors: Invalid credentials, expired tokens
• Authorization errors: Insufficient permissions for workspace access
• Validation errors: Invalid parameters or missing required fields
• API errors: Upstream Magnum API issues
• Network errors: Connection timeouts or failures

Errors follow the JSON-RPC 2.0 error response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Authentication required",
    "data": {
      "error_type": "authentication_error",
      "suggestion": "Use the auth tool to log in first"
    }
  }
}

Security

• Token Management: JWT tokens are automatically refreshed and securely stored
• Configuration Security: Sensitive tokens are stored in configuration files with appropriate permissions
• API Security: All requests include proper authentication headers
• Audit Logging: All operations are logged for security auditing
• No Credential Logging: Passwords and tokens are never logged in plain text

License

This project is part of the Magnum workspace management system. See LICENSE file for details.

Support

For issues, questions, or contributions:

• File issues in the project repository
• Review the MCP protocol specification
• Check the Magnum API documentation
• Ensure proper authentication and workspace permissions