Freedcamp MCP Server

This is a Model Context Protocol (MCP) server implementation for Freedcamp task management. It provides tools for creating, updating, listing, and deleting tasks in Freedcamp projects with support for bulk operations.

Available Transport Methods:

STDIO Transport - Traditional MCP transport for IDE integrations (Claude Desktop, Cursor, etc.)
HTTP Transport - Modern REST API with Server-Sent Events for web applications and cloud deployments

Features

Create multiple tasks in a single operation with title, description, priority, due date, and assignee
Update existing tasks including status changes
List all tasks in a project
Delete tasks permanently
Bulk operations support for all task management operations
Environment variable support for credentials
Comprehensive error handling and validation

Prerequisites

Node.js 17 or higher
TypeScript
Freedcamp account with API access
API Key and Secret from Freedcamp
Project ID from Freedcamp

Installation (for manual invocation only, not necessary for usage with an IDE or other MCP desktop client)

Clone the repository:

git clone <repository-url>
cd freedcamp-mcp

Install dependencies:

npm install

Create a .env file in the root directory with your Freedcamp credentials:

FREEDCAMP_API_KEY=your_api_key
FREEDCAMP_API_SECRET=your_api_secret
FREEDCAMP_PROJECT_ID=your_project_id

Usage

Running the Server

First build the TypeScript code:

npm run build

STDIO Transport (Default)

This is the traditional transport method used by IDEs and MCP clients:

npm start

HTTP Transport

For containerized deployments and HTTP-based integrations:

Development (with .env file):

npm run start:http:test

Production (with environment variables):

npm run start:http

Direct execution:

# With environment variables
FREEDCAMP_API_KEY=your_key FREEDCAMP_API_SECRET=your_secret FREEDCAMP_PROJECT_ID=your_project npm run start:http

# Or using npx
npx freedcamp-mcp --http

The HTTP server will start on port 3000 (or the port specified by the PORT environment variable) and provide:

MCP endpoint: http://localhost:3000/mcp
Health check: http://localhost:3000/health

HTTP Transport Features:

Stateless operation - each request is independent
JSON responses with proper error handling
CORS support for web applications
Built-in health monitoring
Suitable for load balancing and clustering

Docker Deployment

For production deployments, you can use Docker to run the HTTP transport:

Using Docker Compose (Recommended)

Create a .env file with your Freedcamp credentials:

FREEDCAMP_API_KEY=your_api_key
FREEDCAMP_API_SECRET=your_api_secret
FREEDCAMP_PROJECT_ID=your_project_id

Start the service:

docker-compose up -d

Using Docker directly

# Build the image
docker build -t freedcamp-mcp .

# Run the container
docker run -d \
  --name freedcamp-mcp \
  -p 3000:3000 \
  -e FREEDCAMP_API_KEY=your_api_key \
  -e FREEDCAMP_API_SECRET=your_api_secret \
  -e FREEDCAMP_PROJECT_ID=your_project_id \
  freedcamp-mcp

The containerized server provides the same MCP functionality via HTTP transport, making it suitable for:

Cloud deployments
Kubernetes environments
Load-balanced setups
Integration with HTTP-based MCP clients

Running the Test Harness

The project includes comprehensive test harnesses that verify all MCP functionality for both transport methods:

STDIO Transport Test:

npm test

HTTP Transport Test:

npm run test:http

Both test harnesses perform the following checks:

Server initialization with proper protocol version
Tool listing and capability verification
Single task creation, update, and deletion
Bulk task operations (create, update, delete)
Task listing and verification
Error handling and edge cases

Note: The HTTP test harness requires the HTTP server to be running. Use npm run start:http:test to start the server with test environment variables loaded.

Available Tools

freedcamp_add_task
- Creates one or more new tasks in Freedcamp
- Input: Object with tasks array containing task details
- Task Parameters:
  - title (required): Task title - should be clear and descriptive
  - description (optional): Detailed description of what the task involves
  - priority (optional): Task priority level (0=Low, 1=Normal, 2=High, 3=Urgent)
  - due_date (optional): Due date as Unix timestamp string (e.g., '1735689600' for 2025-01-01)
  - assigned_to_id (optional): User ID to assign the task to (must be valid Freedcamp user ID)
freedcamp_update_task
- Updates one or more existing tasks in Freedcamp
- Input: Object with tasks array containing task updates
- Task Parameters:
  - task_id (required): ID of the task to update (must be valid existing Freedcamp task ID)
  - title (optional): New task title
  - description (optional): New task description
  - priority (optional): New task priority (0=Low, 1=Normal, 2=High, 3=Urgent)
  - due_date (optional): New due date as Unix timestamp string
  - assigned_to_id (optional): User ID to reassign the task to
  - status (optional): New task status (0=Open, 1=Completed, 2=Closed)
freedcamp_list_tasks
- Retrieves all tasks in the configured Freedcamp project
- No parameters required (uses project ID from environment variables)
- Returns task details including ID, title, status, and other metadata
freedcamp_delete_task
- Permanently deletes one or more tasks from Freedcamp
- Input: Object with tasks array containing task IDs to delete
- Task Parameters:
  - task_id (required): ID of the task to delete (WARNING: This action cannot be undone)

Example Usage

Creating multiple tasks:

{
  "tasks": [
    {
      "title": "Setup project structure",
      "description": "Initialize the basic project folder structure",
      "priority": 2,
      "due_date": "1735689600"
    },
    {
      "title": "Implement authentication",
      "description": "Add user login and registration functionality",
      "priority": 3,
      "assigned_to_id": "12345"
    }
  ]
}

Updating multiple tasks:

{
  "tasks": [
    {
      "task_id": "67890",
      "status": 1,
      "description": "Updated: Added OAuth integration"
    },
    {
      "task_id": "67891",
      "priority": 3,
      "due_date": "1735776000"
    }
  ]
}

Deleting multiple tasks:

{
  "tasks": [
    {
      "task_id": "67892"
    },
    {
      "task_id": "67893"
    }
  ]
}

IDE Integration

The server can be run directly using npx without cloning the repository. Choose between STDIO transport (traditional) or HTTP transport (modern) based on your needs.

Cursor

Option 1: STDIO Transport (Default)

Open (or create) .cursor/mcp.json in your project root.

Add your Freedcamp MCP server configuration:

{
  "mcpServers": {
    "freedcamp": {
      "command": "npx",
      "args": ["freedcamp-mcp"],
      "env": {
        "FREEDCAMP_API_KEY": "your_api_key",
        "FREEDCAMP_API_SECRET": "your_api_secret",
        "FREEDCAMP_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Restart Cursor or reload MCP servers.

Option 2: HTTP Transport

First, start the HTTP server (in a separate terminal):

npx freedcamp-mcp --http
# Or with environment variables:
FREEDCAMP_API_KEY=your_key FREEDCAMP_API_SECRET=your_secret FREEDCAMP_PROJECT_ID=your_project npx freedcamp-mcp --http

Configure Cursor to use HTTP transport:

{
  "mcpServers": {
    "freedcamp": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Cursor or reload MCP servers.

Claude Desktop

Option 1: STDIO Transport (Default)

Open (or create) ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Claude/claude_desktop_config.json on Windows.

Add your Freedcamp MCP server configuration:

{
  "mcpServers": {
    "freedcamp": {
      "command": "npx",
      "args": ["freedcamp-mcp"],
      "env": {
        "FREEDCAMP_API_KEY": "your_api_key",
        "FREEDCAMP_API_SECRET": "your_api_secret",
        "FREEDCAMP_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Restart Claude Desktop.

Option 2: HTTP Transport

Start the HTTP server:
```
npx freedcamp-mcp --http
```

Configure Claude Desktop to use HTTP transport:

{
  "mcpServers": {
    "freedcamp": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Claude Desktop.

Roo

Option 1: STDIO Transport (Default)

Open (or create) your Roo MCP config file (commonly roo.mcp.json or similar).

Add your Freedcamp MCP server configuration:

{
  "mcpServers": {
    "Freedcamp": {
      "transport": "stdio",
      "command": "npx",
      "args": ["freedcamp-mcp"],
      "env": {
        "FREEDCAMP_API_KEY": "your_api_key",
        "FREEDCAMP_API_SECRET": "your_api_secret",
        "FREEDCAMP_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Option 2: HTTP Transport

Start the HTTP server:
```
npx freedcamp-mcp --http
```

Configure Roo to use HTTP transport:

{
  "mcpServers": {
    "Freedcamp": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

API Reference

For detailed information about Freedcamp's API, visit: https://freedcamp.com/api-docs

License

MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Freedcamp

Freedcamp MCP Server

Features

Prerequisites

Installation (for manual invocation only, not necessary for usage with an IDE or other MCP desktop client)

Usage

Running the Server

STDIO Transport (Default)

HTTP Transport

Docker Deployment

Using Docker Compose (Recommended)

Using Docker directly

Running the Test Harness

Available Tools

Example Usage

IDE Integration

Cursor

Claude Desktop

Roo

API Reference

License

Contributing

MCP Now 重磅来袭，抢先一步体验