magnum-mcp by inovait - MCP Server

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.

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

Quick Start

Build the server:

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

Configure API endpoint:

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

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:

Environment variables (highest priority)
Configuration file (magnum-mcp-config.json)
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

Install mcpo (requires Python 3.8+):
```
pip install mcpo uv
```
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
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.
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

The repo includes a preconfigured .air.toml for this project.
Start the live-reloading server:
```
air
```
This will rebuild and restart the server on any code change.
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

Follow Go conventions and use gofmt
Add tests for new functionality
Update documentation for API changes
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

inovait/magnum-mcp

Magnum MCP Server

Table of Contents

Quick Start

Installation

Prerequisites

Build from Source

Verify Installation

Configuration

Environment Variables

Configuration File

Integration Examples

Claude Desktop

Gemini CLI

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

Why use the MCP Proxy (mcpo)?

Quickstart: Run the Proxy Locally

Docker Example

Custom Integration

Available Tools

Authentication

Workspace Management

User Management

Activity Management

Project Management

Reporting

MCP Resources

Development

Live Reload with Air

Install Air

Usage

Project Structure

Building and Testing

Contributing

API Reference

Authentication Flow

Workspace Operations

Activity Management

Resource Access

Error Handling

Security

License

Support

Why use the MCP Proxy (`mcpo`)?