Project Tracking MCP Server

A lightweight Model Context Protocol (MCP) server built with FastMCP that provides project and task management capabilities through a single SQLite database file.

Features

• Project Management

  • Create, list, get, and delete projects

  • Each project has a name, description, and timestamps

• Task Management

  • Add tasks to projects with descriptions and categories

  • Track task status: backlog, in_progress, review, complete

  • Update task status and delete tasks

  • Categories for organizing tasks (e.g., 'testing', 'ux', 'transcription')

• Single-File Database

  • All data stored in a single SQLite file (projects.db)

  • Automatic database initialization

  • Persistent storage with full CRUD operations

Installation

1. Clone the repository:

2. Install dependencies using one of these methods:

Using pip:

Using uv (recommended for FastMCP):

Or install directly:

Usage

Running the Server

Start the MCP server:

Configuring with Claude Desktop

Add this configuration to your Claude Desktop claude_desktop_config.json:

Or use FastMCP's automatic installation:

Configuring with Claude Code

To use this MCP server with Claude Code (Anthropic's official CLI):

1. Install Claude Code (if you haven't already):

   # Install via pip pip install claude-code # Or using uv uv tool install claude-code

2. Add MCP server to Claude Code configuration:

   Create or edit your Claude Code MCP configuration file:

   # Create the config directory if it doesn't exist mkdir -p ~/.claude # Edit the MCP config file nano ~/.claude/mcp_servers.json

3. Add this server configuration:

   { "project-tracker": { "command": "python", "args": ["/absolute/path/to/project-tracking-mcp/server.py", "--mcp-only"], "env": {} } }

4. Update the path in the configuration to point to your actual installation directory:

   { "project-tracker": { "command": "python", "args": ["/home/yourusername/project-tracking-mcp/server.py", "--mcp-only"], "env": {} } }

5. Verify the installation:

   # Test that Claude Code can connect to the server claude-code --list-tools

   You should see the project tracking tools listed:

   • list_projects

   • create_project

   • get_project

   • delete_project

   • create_task

   • update_task_status

   • delete_task

   • get_project_stats

6. Start using with Claude Code:

   # Start Claude Code session claude-code # Now you can use project tracking commands like: # "Create a new project called 'My Web App'" # "Add a task to implement user authentication" # "Show me all my projects and their tasks"

Note: The --mcp-only flag ensures the server runs in MCP mode without starting the HTTP web interface, which is optimal for Claude Code integration.

Available MCP Tools

Project Management

• list_projects(): List all projects with summary information

• create_project(name, description?): Create a new project

• get_project(project_id): Get detailed project information with all tasks

• delete_project(project_id): Delete a project and all its tasks

Task Management

• create_task(project_id, description, category): Add a task to a project

• update_task_status(task_id, status): Update task status

• delete_task(task_id): Delete a task

Statistics

• get_project_stats(): Get overall statistics about projects and tasks

Example Usage

Create a Project

Add Tasks

Update Task Status

Get Project with Tasks

Data Models

Project

• id: Unique identifier (UUID)

• name: Project name

• description: Project description

• created_at: Creation timestamp

• updated_at: Last update timestamp

• tasks: List of associated tasks

Task

• id: Unique identifier (UUID)

• description: Task description

• category: Task category/label

• status: Current status (backlog/in_progress/review/complete)

• created_at: Creation timestamp

• updated_at: Last update timestamp

Database

The server uses SQLite with two tables:

• projects: Stores project information

• tasks: Stores task information with foreign key to projects

The database file (projects.db) is created automatically on first run.

Requirements

• Python 3.10+

• FastMCP

• Pydantic 2.0+

• SQLite (built-in with Python)

License

MIT