What is Habitica Mcp Server

habitica-mcp-server is a server project that integrates with the Habitica API, allowing users to manage their tasks and habits programmatically.

Use cases

Use cases include automating task management, creating custom habit tracking tools, and integrating Habitica functionalities into other applications.

How to use

To use habitica-mcp-server, initialize the project with ‘uv’, add necessary dependencies, configure your Habitica API credentials in a secure file, and run the server to access user tasks.

Key features

Key features include easy integration with the Habitica API, support for retrieving user tasks, and a simple setup process using environment variables for secure credential management.

Where to use

habitica-mcp-server can be used in personal productivity applications, habit tracking systems, and any project that requires interaction with the Habitica platform.

Project Title

A brief description of your project that uses the Habitica API.

Setup

1. Initialize and add dependencies with uv:

   uv init habitica-mcp-server
   cd habitica-mcp-server
   uv add "mcp[cli]" httpx aiohttp python-dotenv
   

2. API Configuration:

   You need to obtain your Habitica User ID and API Key. You can find these in your Habitica account settings under API.

   Create a file (e.g., .env or config.py) to store your credentials securely. Do NOT commit your credentials directly into your code.

   # Example config.py
   HABITICA_API_KEY = "YOUR_API_KEY"
   HABITICA_USER_ID = "YOUR_USER_ID"
   HABITICA_API_URL = "https://habitica.com/api/v3"
   

Usage

Here is a simple example of how to use the HabiticaClient:

from mcp.server.fastmcp import FastMCP
from habitica_client import HabiticaClient
import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Create an MCP server
mcp = FastMCP("Habitica Integration")   

# Initialize Habitica client
habitica_client = HabiticaClient(
    api_key=os.getenv("HABITICA_API_KEY"),
    user_id=os.getenv("HABITICA_USER_ID"),
    api_url=os.getenv("HABITICA_API_URL")


@mcp.tool()
async def get_user_tasks(task_type: str = "") -> list:
    """Get all tasks for the authenticated user
    Args:
        task_type: Optional filter for task type (habits, dailys, todos, rewards, completedTodos)
    """
    return await habitica_client.get_user_tasks(task_type)

if __name__ == "__main__":
    mcp.run()

To test locally using mcp, run:

mcp dev main.py

Replace "YOUR_API_KEY" and "YOUR_USER_ID" with your actual Habitica API credentials.