# MCP Server Setup
This document outlines the steps necessary to run this MCP server and connect to an MCP host application, such as Claude Desktop or Cursor.
## Quick Setup
The easiest way to use this MCP server is with npx:
```bash
npx @doist/todoist-ai
```
You'll need to set your Todoist API key as an environment variable `TODOIST_API_KEY`.
## Local Development Setup
Start by cloning this repository and setting it up locally, if you haven't done so yet.
```sh
git clone https://github.com/Doist/todoist-ai
npm run setup
```
To test the server locally before connecting it to an MCP client, you can use:
```sh
npm start
```
This will build the project and run the MCP inspector for manual testing.
### Creating a Custom MCP Server
For convenience, we also include a function that initializes an MCP Server with all the tools available:
```js
import { getMcpServer } from "@doist/todoist-ai";
async function main() {
const server = getMcpServer({ todoistApiKey: process.env.TODOIST_API_KEY });
const transport = new StdioServerTransport();
await server.connect(transport);
}
```
Then, proceed depending on the MCP protocol transport you'll use.
## Using Standard I/O Transport
### Quick Setup with npx
Add this section to your `mcp.json` config in Claude, Cursor, etc.:
```json
{
"mcpServers": {
"todoist-ai": {
"type": "stdio",
"command": "npx",
"args": ["@doist/todoist-ai"],
"env": {
"TODOIST_API_KEY": "your-todoist-token-here"
}
}
}
}
```
### Using local installation
Add this `todoist-ai-tools` section to your `mcp.json` config in Cursor, Claude, Raycast, etc.
```json
{
"mcpServers": {
"todoist-ai-tools": {
"type": "stdio",
"command": "node",
"args": ["/Users/<your_user_name>/code/todoist-ai-tools/dist/main.js"],
"env": {
"TODOIST_API_KEY": "your-todoist-token-here"
}
}
}
}
```
Update the configuration above as follows
- Replace `TODOIST_API_KEY` with your Todoist API token.
- Replace the path in the `args` array with the correct path to where you cloned the repository
> [!NOTE]
> You may also need to change the command, passing the full path to your `node` binary, depending one how you installed `node`.
## Using Streamable HTTP Server Transport
You can run the MCP server as an HTTP service with configurable session timeouts. This is useful as an alternative to the hosted service at `ai.todoist.net/mcp`, especially if you experience frequent session disconnections ([#239](https://github.com/Doist/todoist-ai/issues/239)).
### Quick Start with npx
```bash
# Default: 30 minute session timeout
TODOIST_API_KEY=your-key npx -p @doist/todoist-ai todoist-ai-http
# Custom timeout: 1 hour (3600000ms)
TODOIST_API_KEY=your-key SESSION_TIMEOUT_MS=3600000 npx -p @doist/todoist-ai todoist-ai-http
# Custom port
TODOIST_API_KEY=your-key PORT=8080 npx -p @doist/todoist-ai todoist-ai-http
```
### Running from Source
After cloning the repository:
```bash
# Install dependencies and build
npm install && npm run build
# Run the HTTP server
TODOIST_API_KEY=your-key npm run start:http
# Or directly with node
TODOIST_API_KEY=your-key node dist/main-http.js
```
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `TODOIST_API_KEY` | (required) | Your Todoist API key |
| `PORT` | `3000` | HTTP server port |
| `SESSION_TIMEOUT_MS` | `1800000` | Session timeout in milliseconds (30 min default) |
| `TODOIST_BASE_URL` | (optional) | Custom Todoist API base URL |
### Local Development
```sh
PORT=8080 npm run dev:http
```
This will expose the service at `http://localhost:8080/mcp` with hot-reload.
### Connecting MCP Clients
MCP host applications can connect via the `mcp-remote` bridge:
```json
{
"mcpServers": {
"todoist-mcp-http": {
"type": "stdio",
"command": "npx",
"args": ["mcp-remote", "http://localhost:3000/mcp"]
}
}
}
```
### Health Check
The HTTP server exposes a health check endpoint at `/health` that returns:
- Server status
- Number of active sessions
- Configured session timeout
```bash
curl http://localhost:3000/health
```
> [!NOTE]
> You may also need to change the command, passing the full path to your `npx` binary, depending on how you installed `node`.
## MCP Apps (task-list) build pipeline
- The task list widget is bundled and inlined **at Vite build time** via a custom plugin (`virtual:todoist-ai-widgets`).
- The plugin uses `BUILD_TIMESTAMP` (from `process.env.BUILD_TIMESTAMP` or auto-generated) to cache-bust the widget URI (e.g., `task-list-<timestamp>.html`).
- The final HTML is **embedded in the JS bundle**; the runtime MCP server does **not** read from `dist/` to find widget files.
- `npm run build` is sufficient
