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

Or use with npx (no installation needed):

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

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:

mark_as_done

Mark a todo item as completed.

Parameters:

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

Example usage:

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:

remove_todo

Delete a todo item.

Parameters:

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

Example usage:

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