db4app-todo-mcp-server

MCP server for db4.app todo list app - enables LLMs to manage todos via Model Context Protocol using the Postgres TCP protocol.

Installation

npm install -g db4app-todo-mcp-server

Or use with npx (no installation needed):

npx db4app-todo-mcp-server

Usage

Important: This MCP server uses the Postgres TCP protocol to connect directly to your browser database, just like psql or other Postgres clients. It uses TLS encryption and password authentication.

With LM Studio

1. Locate your

   • macOS: ~/Library/Application Support/LM Studio/mcp.json

   • Windows: %APPDATA%\LM Studio\mcp.json

   • Linux: ~/.config/LM Studio/mcp.json

2. Get your Connection ID and Auth Token:

   • Open the Database page in your browser

   • Your Connection ID is displayed in the Connection Info section

   • Your Auth Token is also shown in the Connection Info section (this is your password)

3. Install the todo-mcp app from the Community Apps page in db4.app

4. Add this to the

{
  "mcpServers": {
    "db4app-todo": {
      "command": "npx",
      "args": [
        "-y",
        "db4app-todo-mcp-server@latest"
      ],
      "env": {
        "MCP_POSTGRES_URL": "postgres://postgres:YOUR_AUTH_TOKEN@YOUR_CONNECTION_ID.pg.db4.app",
        "MCP_SCHEMA": "todo_mcp"
      }
    }
  }
}

Important Notes:

• Replace YOUR_AUTH_TOKEN with your actual auth token from step 2

• Replace YOUR_CONNECTION_ID with your Connection ID from step 2

• The connection string format is: postgres://postgres:AUTH_TOKEN@CONNECTION_ID.pg.db4.app

• Each browser tab has its own unique Connection ID and Auth Token - make sure you use the correct ones

• Postgres TCP Protocol: The MCP server uses the standard Postgres wire protocol with TLS encryption, just like psql or DBeaver

5. Restart LM Studio to load the new MCP server configuration.

With Claude Desktop

1. Locate your Claude Desktop config:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the same configuration as above to the mcpServers object.

3. Restart Claude Desktop.

Available Tools

add_todo

Add a new todo item to the list.

Parameters:

• title (required): The title of the todo item

• description (optional): Additional details

• category (optional): Category name (e.g., "Work", "Personal", "Shopping")

• priority (optional): Priority level (0=normal, 1=high, 2=urgent, default: 0)

• due_date (optional): Due date in ISO format (e.g., "2024-12-31T23:59:59Z")

Example usage:

"Add a todo to finish the project report by end of month, high priority, in the Work category"

mark_as_done

Mark a todo item as completed.

Parameters:

• todo_id (required): The ID of the todo to mark as done

Example usage:

"Mark todo #5 as done"
"Complete the todo about finishing the report"

list_todos

List all todos with optional filters.

Parameters:

• show_completed (optional): Show completed todos (default: true)

• category (optional): Filter by category name

• priority (optional): Filter by priority level (0, 1, or 2)

Example usage:

"Show me all my pending todos"
"List all high priority todos in the Work category"
"What todos do I have due today?"

remove_todo

Delete a todo item.

Parameters:

• todo_id (required): The ID of the todo to remove

Example usage:

"Delete todo #3"
"Remove the todo about buying groceries"

Environment Variables

• MCP_POSTGRES_URL: Postgres connection URL (format: postgres://postgres:AUTH_TOKEN@CONNECTION_ID.pg.db4.app)

• MCP_SCHEMA: Schema name for todo tables (default: todo_mcp)

• MCP_CONNECTION_ID: Browser connection ID (alternative to full URL)

• MCP_AUTH_TOKEN: Auth token for authentication (alternative to full URL)

Troubleshooting

Connection Issues

• Postgres TCP Protocol: The MCP server uses the standard Postgres wire protocol with TLS encryption, just like psql or DBeaver

• Connection String Format: postgres://postgres:AUTH_TOKEN@CONNECTION_ID.pg.db4.app

• Auth Token Required: You must provide the auth token in the connection string (it's your password)

• TLS Encryption: Connections are automatically encrypted using TLS (no additional configuration needed)

Password Authentication Failed

If you see FATAL: Password authentication failed:

1. Get your Auth Token: Open the Database page → Connection Info section

2. Use the exact token: Copy the token and use it in your connection string

3. Token persistence: The token is auto-generated and stored in your browser's localStorage

4. Single error message: You should see only ONE error message. If you see multiple errors, please report it as a bug.

Schema Not Found

If you see errors about the schema not existing:

1. Install the app: Make sure you've installed the "Todo List with MCP" app from the Community Apps page

2. Check schema name: Verify MCP_SCHEMA matches the schema name (default: todo_mcp)

3. Verify installation: Run SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'todo_mcp'; to confirm the schema exists

License

MIT