Task Manager MCP Server

How to use

You use a MCP client to connect to the Task Manager server and perform common task operations such as listing, adding, updating, and removing tasks. Run the server locally and then connect from your MCP client to manage your tasks through the exposed endpoints or commands. When running in stdio mode, you start the server as a local process and send commands through the MCP protocol. When running in HTTP mode, you expose an HTTP interface to perform the same actions.

How to install

Prerequisites you need before installing: a modern runtime that can execute MCP servers (Bun is recommended). Ensure you have a working shell and permission to run commands on your machine.

Step 1: Install Bun (if you do not already have it). Visit the Bun website and follow the installation instructions for your operating system.

Step 2: Run the Task Manager server using Bun with a specific tasks file path.

bunx @abyssbug/task-manager --tasks-file ~/Documents/tasks.json

Step 3: Alternative using an environment variable to specify the file path. The default path is ~/Documents/tasks.json if you omit the variable.

TASK_MANAGER_FILE_PATH=/Users/you/Documents/tasks.json bunx @abyssbug/task-manager

Step 4: If Bun is not available, you can run it with npx as long as Bun is installed in your environment.

npx -y @abyssbug/task-manager --tasks-file ~/Documents/tasks.json

Additional configuration and notes

You can configure how the MCP client launches the Task Manager by using MCP configuration blocks for your client. The server also supports an HTTP transport mode, which you can enable by setting MCP_TRANSPORT=http when starting the server so that it exposes HTTP endpoints in addition to the standard MCP interface.

Configuration and security

Use a specific file path for your tasks.json to keep your data organized and separate from other projects. If you want to run the server under a different user or directory, adjust the working directory and file path accordingly.

Troubleshooting and tips

If the server does not start, verify that Bun or Node is installed and accessible from your shell, and confirm that the path to the tasks.json file exists and is writable. When using HTTP mode, check that MCP_TRANSPORT is set to http and that the server is listening on the expected port. If you encounter permissions issues, run the commands with appropriate user permissions or adjust the file permissions of your tasks.json.

Example usage patterns

- Start the server with a specific tasks file path using Bun and immediately connect with an MCP client to manage tasks.

MCP config example blocks

{
  "mcpServers": {
    "task_manager": {
      "type": "stdio",
      "name": "task_manager",
      "command": "bunx",
      "args": ["@abyssbug/task-manager", "--tasks-file", "/Users/you/Documents/tasks.json"],
      "env": [
        {"name": "TASK_MANAGER_FILE_PATH", "value": "/Users/you/Documents/tasks.json"}
      ]
    }
  }
}

Notes on HTTP mode

If you enable HTTP mode, you will expose additional endpoints to interact with the Task Manager over HTTP. This can be useful for integrating with web dashboards or other HTTP-based tools.

Mobility and scaling considerations

This MCP server is lightweight and is designed to work with a simple tasks.json file. For multi-user environments or larger task datasets, consider using a database-backed solution and wiring it through the MCP interface to maintain performance and data integrity.

health

Health check endpoint returns { ok: true } to verify the server is running.

tools

Returns a list of available MCP tools when queried from /tools.

call

Accepts a tool name and arguments to execute an MCP tool call via POST to /call.