🚀 Enhanced Freedcamp MCP Server

A comprehensive Model Context Protocol (MCP) server for seamless integration with the Freedcamp API. This server provides enterprise-level project management capabilities with advanced filtering, full CRUD operations, and extensive customization options.

✨ Features

🏗️ Project Management

List projects with optional recent project tracking
Detailed project information including users, notifications, and capabilities
Create/Update/Delete projects with user management
Manage project teams (add, update, remove users)
Group management and project organization

📋 Advanced Task Management

Comprehensive task filtering with 15+ filter options:
- Status filtering (not started, completed, in progress)
- User assignment filtering (assigned to, created by)
- Date range filtering (due dates, creation dates)
- Priority-based filtering and ordering
- Custom fields and tags support
Full task lifecycle - Create, Read, Update, Delete
Subtask support with parent-child relationships
File attachments and media management
Recurring tasks with iCalendar format support
Pagination and ordering for large datasets

👥 User Management

Complete user profiles with detailed information
Current user management and profile updates
User task assignments and workload tracking
Email and password management with secure token handling

💬 Comment System

Add/Update/Delete comments on tasks and items
File attachments in comments
Rich text support with HTML formatting
Comment threading and user attribution

📁 File Management

File details and metadata access
File deletion and cleanup
Multi-format support (images, documents, etc.)
Temporary file handling for uploads

🛠️ Installation & Setup

Prerequisites

Docker and Docker Compose
Freedcamp API credentials (API Key)

Quick Start

Clone the repository:

git clone https://github.com/BluePointDigital/freedcamp-mcp-server.git cd freedcamp-mcp-server

Set up environment variables:

cp env-example.sh .env # Edit .env and add your Freedcamp credentials

Start the services:

docker-compose up -d

Access the API:

MCP Server: http://localhost:8000/mcp/
OpenAPI Proxy: http://localhost:8111
API Documentation: http://localhost:8111/docs

🔧 Configuration

Environment Variables

Create a .env file with your Freedcamp credentials:

FREEDCAMP_API_KEY=your_api_key_here FREEDCAMP_API_SECRET=your_api_secret_here # Optional for some endpoints

Docker Configuration

The included docker-compose.yml provides:

Health checks for service monitoring
Restart policies for reliability
Resource limits for optimal performance
Network isolation for security

🔥 Workflow Instructions for LLMs

IMPORTANT: This MCP server includes comprehensive workflow guidance to ensure proper usage:

Server Description: Built-in instructions provided when LLMs first connect
get_workflow_help(): Contextual workflow guidance for specific operations
Enhanced Tool Docstrings: Workflow reminders in critical tools like create_task()
Workflow Documentation: See freedcamp-workflow-instructions.md for detailed guidance

Key Rule: Always call get_projects() and get_users() first to look up IDs before using them in operations!

📚 API Reference

🏗️ Project Tools

Tool	Description	Parameters
`get_projects`	List all projects with grouping	`include_recent: bool`
`get_project_details`	Detailed project information	`project_id: str`
`create_project`	Create new project with team	`name, description, color, users...`
`update_project`	Update project and manage users	`project_id, name, users_to_add...`
`delete_project`	Remove project	`project_id: str`

📋 Task Tools

Tool	Description	Key Features
`get_all_tasks`	Advanced task filtering	15+ filter options, pagination
`get_project_tasks`	Project-specific tasks	Status filtering, custom fields
`get_user_tasks`	User assignment tracking	Completed task inclusion
`get_task_details`	Complete task information	Comments, files, custom fields
`create_task`	Enhanced task creation	Subtasks, files, recurring rules
`update_task`	Full task modification	All properties, custom fields
`delete_task`	Task removal	Cascade handling

👥 User Tools

Tool	Description	Capabilities
`get_users`	List all workspace users	Full profile data
`get_current_user`	Current user information	Profile details
`get_user_details`	Specific user data	`user_id: str`
`update_current_user`	Profile management	Email, password, timezone

💬 Comment Tools

Tool	Description	Features
`add_comment`	Create comments	File attachments, HTML support
`update_comment`	Modify comments	Rich text editing
`delete_comment`	Remove comments	Clean deletion

📁 File Tools

Tool	Description	Capabilities
`get_file_details`	File information	Metadata, URLs, thumbnails
`delete_file`	File removal	Clean deletion

🔍 Usage Examples

Advanced Task Filtering

# Get overdue high-priority tasks assigned to specific users await get_all_tasks( status_filter=["0", "2"], # Not started or in progress assigned_to_ids=["123", "456"], due_date_to="2024-01-01", # Overdue order_by="priority", order_direction="desc", limit=50 )

Project Team Management

# Add users to a project await update_project( project_id="789", users_to_add=[ {"email": "user@example.com", "first_name": "John", "last_name": "Doe"}, {"email": "admin@example.com", "first_name": "Jane", "last_name": "Admin"} ] )

Task Creation with Subtasks

# Create a parent task with subtasks and files parent_task = await create_task( title="Main Project Phase", project_id="123", priority=3, # High priority due_date="2024-12-31" ) # Create subtask await create_task( title="Subtask 1", project_id="123", parent_task_id=parent_task["task"]["id"], attached_file_ids=[456, 789] )

🏗️ Architecture

Components

FastMCP Core: High-performance MCP server framework
Freedcamp API Client: Secure, authenticated API wrapper
MCPO Proxy: OpenAPI generation and REST interface
Docker Environment: Containerized deployment with health monitoring

Key Features

Robust Error Handling: Comprehensive error management and logging
Data Formatting: Consistent response structures across all endpoints
Security: Secure credential management and API authentication
Performance: Optimized queries with pagination and filtering
Reliability: Health checks, restart policies, and connection management

🐳 Deployment

Production Deployment

Environment Setup:

# Production environment file FREEDCAMP_API_KEY=prod_api_key FREEDCAMP_API_SECRET=prod_api_secret

Service Scaling:

docker-compose up -d --scale freedcamp-fastapi=3

Health Monitoring:

docker-compose ps # Check service health docker-compose logs -f # Monitor logs

Development Mode

# Start with hot-reload docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

🔧 Development

Project Structure

freedcamp-mcp-server/ ├── freedcamp_mcp.py # Main MCP server implementation ├── docker-compose.yml # Docker services configuration ├── Dockerfile # Container definition ├── requirements.txt # Python dependencies ├── healthcheck.py # Health monitoring ├── .env # Environment variables ├── .gitignore # Git ignore rules └── README.md # This file

Adding New Features

Implement the method in FreedcampMCP class
Add the tool decorator in _setup_tools()
Update documentation and examples
Test with Docker Compose

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Issues: GitHub Issues
Documentation: Freedcamp API Docs
MCP Protocol: Model Context Protocol

🎯 Roadmap

File Upload Support: Direct file upload capabilities
Webhook Integration: Real-time notifications
Advanced Reporting: Analytics and reporting tools
Bulk Operations: Mass task and project management
Custom Field Templates: Dynamic custom field management
Integration Tests: Comprehensive test suite
Performance Optimization: Query caching and optimization

⭐ Star this repository if it helps you manage your Freedcamp projects more effectively!

Made with ❤️ for the Freedcamp and MCP communities.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that enables seamless integration with Freedcamp API for enterprise-level project management with advanced filtering, full CRUD operations, and extensive customization options.

Related MCP Servers

Nash MCP Server
nash-app
-
security
A
license
-
quality
A Model Context Protocol server that enables seamless execution of commands, Python code, web content fetching, and reusable task management with secure credentials handling.
Last updated -
2
MIT License
Context Manager MCP Server
docherty
-
security
A
license
-
quality
A server implementation of the Model Context Protocol (MCP) for managing development workflow with features like project management, task tracking, and QA review support.
Last updated -
3
AGPL 3.0
Task Manager MCP Server
tradesdontlie
-
security
A
license
-
quality
A Model Context Protocol server providing comprehensive task management capabilities with support for project organization, task tracking, and automatic PRD parsing into actionable items.
Last updated -
25
MIT License
Memory Bank MCP Server
nicavcrm
A
security
F
license
A
quality
A Model Context Protocol server that provides structured workflow tools for managing software development projects through different complexity levels, offering specialized modes for project planning, design, implementation, and documentation.
Last updated -
5
33
1

View all related MCP servers