Stores and manages todo list data using Firebase Firestore, providing persistent storage for tasks with operations like create, list, update, complete, and delete todos.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Firestore Todo List MCP Server add 'buy groceries' to my todo list for tomorrow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect any MCP Client like Claude, Open-WebUI and others to this MCP server to manage todos via AI chat in an opinionated way.
You can simply tell the model to create_todo, list_todos, update_todo, 'complete_todo' and delete_todo
You can setup a custom system prompt as well to get customized answers.
Works very well with Claude, OpenAI and Deepseek models (paid versions). Local models in Ollama also works, but with limitations.
Data is stored on Firebase Firestore because it is "free" for personal usage, easy to run, and easy to setup.
This is an experimental project I created just for learning purposes.
Feel free to try.
Edit the claude_desktop_config.json or the mcp configuration file of your LLM client
{
"mcpServers": {
"firestoreTodoMcp": {
"command": "npx",
"args": [
"firestore-todo-mcp"
],
"env": {
"FIREBASE_SERVICE_ACCOUNT": "base64(serviceAccount.json)",
"FIREBASE_PROJECT_ID": "your-firebase-project-id",
"FIRESTORE_COLLECTION": "test_collection"
},
"type": "stdio"
}
}
}Don't forget to setup your project on Firebase and to get the Firebase serviceAccount from the project's configuration.
The file content must be 'base64' encoded when passing the value to the json above.
Related MCP server: Todoist MCP Server
git clone https://github.com/gtoshinakano/firebase-todo-mcp.git
cd firebase-todo-mcpInstall firebase-tools cli, do firebase login, install emulators and run
firebase emulators:start --only firestore --project local-todo-devCheck if all tools are working fine, test input parameters, output params
npx @modelcontextprotocol/inspector \
-e FIRESTORE_EMULATOR_HOST=localhost:3333 \
-e FIREBASE_PROJECT_ID=local-todo-dev \
-e FIRESTORE_COLLECTION=test_collection \
tsx bin/index.ts{
"mcpServers": {
"firestore-todo": {
"command": "node",
"args": ["/absolute/path/to/dist/bin/index.js"],
"env": {
"FIRESTORE_EMULATOR_HOST": "localhost:3333",
"FIREBASE_PROJECT_ID": "local-todo-dev",
"FIRESTORE_COLLECTION": "test_collection"
}
}
}
}Copy the contents of the system prompts from the path example/
complete: More effective, but token expensive
short: Shorter version for saving tokens. Works fine but less accurate
Try chat like:
Add the task XYZ. Due date tomorrow.
You can be more specific and tell the situation:
I forgot to talk to John regarding XYZ on Friday and I need this ASAP
Or you can be broad and Claude will try to help you split the big task into smaller ones (doesn't work well with Ollama models :/):
I need to create my XYZ Vague Project
Mark an existing todo item as completed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Required. ID of the todo to complete | |
| archive | No | If set to true, archive the todo upon completion | |
| completionNotes | No | Optional completion notes to attach when marking completed |
| Name | Required | Description |
|---|---|---|
| todo | Yes | The affected todo item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action ('Mark as completed'). It doesn't disclose behavioral traits such as permissions needed, whether completion is reversible, error handling, or how it interacts with other tools. This is inadequate for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero waste—it directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values) and 100% schema coverage, the description's minimal content is somewhat acceptable. However, as a mutation tool with no annotations, it should provide more behavioral context to be complete, leaving gaps in understanding its full impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional meaning beyond what's in the schema, such as explaining parameter interactions or usage nuances. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark as completed') and target ('an existing todo item'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'update_todo' which might also handle completion status changes, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_todo' or 'delete_todo'. It mentions 'existing todo item' but doesn't specify prerequisites or exclusions, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new todo/task item to the user's store
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Todo/Task text to add | |
| details | No | Optional. Todo/Task description with details. Max 20 words | |
| completed | No | Initial completed status. Default false | |
| dueDate | No | Optional ISO 8601 due date | |
| role | Yes | User defined role of the person who has to do this todo or task | |
| classification | No | Required. Determined based on the nature of the task: - circumstantial: tasks that arise due to specific situations or events and has low or none aggregating value - urgent: tasks that require immediate attention - important: tasks that are significant and brings value to life, work or goals | important |
| Name | Required | Description |
|---|---|---|
| todo | Yes | The affected todo item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions adding an item but fails to describe key traits like whether this is a write operation (implied but not stated), authentication needs, error handling, or what the output contains (though an output schema exists). This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, mutation operation) and the presence of an output schema, the description is minimally adequate. However, with no annotations and incomplete behavioral transparency, it lacks details on permissions, side effects, or error cases, which are important for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all parameters. The description adds no additional meaning or context beyond what's in the schema, such as explaining parameter interactions or usage examples. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a new todo/task item') and target ('to the user's store'), which is specific and unambiguous. However, it doesn't differentiate this tool from its sibling 'update_todo' or explain why one would create versus update, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_todo' or 'complete_todo', nor does it mention prerequisites or contextual cues. It merely states what the tool does without indicating appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a todo item from the user's Firestore 'todos' collection by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID of the todo to delete |
| Name | Required | Description |
|---|---|---|
| deletedId | Yes | ID of the deleted todo item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the destructive nature ('Delete') but does not mention behavioral traits like permissions required, whether deletion is permanent or reversible, error handling, or confirmation prompts. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key action and resource. It contains zero waste, making it appropriately sized and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple deletion with one parameter), high schema coverage (100%), and presence of an output schema (which handles return values), the description is mostly complete. However, it lacks details on behavioral aspects like permissions or reversibility, which are important for a destructive operation, slightly reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the 'id' parameter fully. The description adds no additional meaning beyond what the schema provides (e.g., format constraints or examples). With high schema coverage, the baseline is 3, as the description does not compensate but also does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete'), resource ('a todo item'), and scope ('from the user's Firestore 'todos' collection by id'), distinguishing it from sibling tools like 'create_todo' or 'update_todo'. It precisely defines what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying deletion by ID, but does not explicitly state when to use this tool versus alternatives (e.g., 'complete_todo' for marking as done) or any prerequisites. It provides basic context but lacks explicit guidance on exclusions or comparisons with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List todo items from the user's 'todos' store with optional filters.
| Name | Required | Description | Default |
|---|---|---|---|
| completed | No | If set, filter todos by completion status | |
| archived | No | If set, filter todos by archived status | |
| from | No | Optional ISO 8601 date. If set, filter todos from this date (inclusive) based on createdAt | |
| to | No | Optional ISO 8601 date. If set, filter todos to this date (inclusive) based on updatedAt | |
| role | No | If set, filter todos by user role | |
| limit | No | Maximum number of todos to return. Default 50 |
| Name | Required | Description |
|---|---|---|
| todos | Yes | List of todos after applying filters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'list' and 'optional filters' but lacks critical behavioral details: whether this is a read-only operation, if it requires authentication, pagination behavior beyond the limit parameter, rate limits, or what happens when no filters are applied. The description is minimal and doesn't compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose. It's front-loaded with the core action and resource, with no wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no annotations, but with 100% schema coverage and an output schema (which handles return values), the description is minimally adequate. However, for a tool with multiple siblings and no annotations, it should provide more context about usage scenarios and behavioral traits to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no additional parameter semantics beyond mentioning 'optional filters' generically, which is already implied by the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('todo items from the user's todos store') with optional filtering. It distinguishes from siblings like create_todo or delete_todo by focusing on retrieval, but doesn't explicitly differentiate from other potential list operations (though none exist in siblings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. The description mentions optional filters but doesn't specify scenarios for using filters or how this tool relates to other todo operations like complete_todo or update_todo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields of an existing todo item (text, completed, dueDate, role).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Required. ID of the todo to update | |
| title | No | New title (if updating) | |
| details | No | New details (if updating) | |
| completed | No | New completed status (if updating) | |
| archived | No | New archived status (if updating) | |
| dueDate | No | New due date (if updating) | |
| completionNotes | No | Completion notes (if provided). Only update when marking as completed. | |
| role | No | New role (if updating). Cannot be empty string | |
| classification | No | Must be provided at the time of task creation based on the nature of the task | important |
| Name | Required | Description |
|---|---|---|
| todo | Yes | The affected todo item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action of updating fields. It doesn't disclose behavioral traits such as whether updates are idempotent, what permissions are required, how errors are handled, or the impact on existing data. The mention of 'existing todo item' implies mutation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action. It could be slightly more structured by grouping fields or adding brief context, but it avoids redundancy and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, mutation operation) and no annotations, the description is incomplete—it lacks behavioral context, usage guidelines, and error handling. However, the presence of an output schema reduces the need to explain return values, and the schema covers parameters well, making it minimally adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 9 parameters. The description adds minimal value by listing some updatable fields (text, completed, dueDate, role) but omits others like archived, completionNotes, and classification, and doesn't clarify semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update fields') and resource ('existing todo item'), and lists specific fields that can be updated. It distinguishes from siblings like create_todo (new items) and delete_todo (removal), though not explicitly. However, it doesn't fully differentiate from complete_todo which might overlap with updating the completed field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like complete_todo or create_todo. It mentions updating fields but doesn't specify prerequisites (e.g., requires an existing todo ID) or contextual cues (e.g., use for partial updates vs. complete_todo for marking as done).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.5complete_todocreate_tododelete_todolist_todosupdate_todoScored across 5 tools
Each tool has a clearly distinct purpose targeting specific CRUD operations on todo items: create, list, update, delete, and complete. No overlap exists between tools, making it easy for an agent to select the correct one based on the intended action.
All tool names follow a consistent verb_noun pattern with 'todo' as the noun (e.g., create_todo, list_todos). The naming is uniform, using snake_case throughout, which enhances readability and predictability for agents.
With 5 tools, this server is well-scoped for a todo list domain, covering essential operations without bloat. Each tool earns its place by providing core functionality, making the set efficient and manageable for typical use cases.
The toolset offers complete CRUD coverage for todo items, including create, read (list), update, delete, and a specialized complete action. There are no obvious gaps; agents can perform all necessary lifecycle operations without dead ends.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
