StartInfinity MCP Server

A Model Context Protocol (MCP) server that provides comprehensive tools for managing StartInfinity projects via their API.

Features

This MCP server exposes 21 tools for interacting with the StartInfinity API:

Workspace & Board Management

1. fetch_dashboard - Returns workspace information
2. fetch_boards - Lists all boards in a workspace
3. fetch_board - Gets detailed information about a specific board
4. create_board - Creates a new board in a workspace
5. delete_board - Deletes a board from a workspace

Folder Management

1. fetch_folders - Lists all folders in a board
2. create_folder - Creates a new folder in a board
3. delete_folder - Deletes a folder from a board

Item Management

1. fetch_items - Lists items from a board (with optional folder filter and pagination)
2. fetch_items_by_attribute - Fetches items filtered by attribute name and value
3. fetch_item_details - Gets detailed information about a specific item
4. fetch_item_json - Fetches item data as JSON with attribute names as keys
5. create_item - Creates a new item in a board folder
6. update_item - Updates attributes of an existing item
7. delete_item - Deletes (archives) an item from a board

Attributes & Views

1. fetch_attributes - Lists all attributes for a board
2. fetch_view - Gets view configuration for a specific view

Members & Formatting

1. fetch_members - Lists all members in a workspace
2. fetch_items_formatted - Fetches items with formatted attributes and titles for reporting

Comments & Snapshots

1. post_comment - Creates a comment on a specific item
2. fetch_folder_snapshot - Provides a snapshot report of items in progress and pending

Prerequisites

• Node.js 18+
• A StartInfinity account with API access
• A Personal Access Token from StartInfinity
• Docker (optional, for containerized deployment)

Getting Started

Quick Start

1. Clone the repository:

   git clone <repository-url>
   cd startinfinity-mcp-server
   

2. Install dependencies:

   npm install
   

3. Configure environment variables:

   Copy .env.example to .env:

   cp .env.example .env
   

   Edit .env and add your credentials:

   STARTINFINITY_API_TOKEN=your_api_token_here
   STARTINFINITY_WORKSPACE_ID=your_workspace_id_here
   

   Important: The STARTINFINITY_WORKSPACE_ID is required and must be set in the environment variable. It is no longer accepted as a tool parameter.

4. Build the project:

   npm run build
   

5. Run the server:

   npm start
   

Docker Setup

Building the Docker Image

docker build -t startinfinity-mcp-server:latest .

Running with Docker

Using docker run:

docker run -it --rm \
  -e STARTINFINITY_API_TOKEN=your_api_token_here \
  -e STARTINFINITY_WORKSPACE_ID=your_workspace_id_here \
  startinfinity-mcp-server:latest

Using docker-compose:

1. Create a .env file with your credentials:

   STARTINFINITY_API_TOKEN=your_api_token_here
   STARTINFINITY_WORKSPACE_ID=your_workspace_id_here
   

2. Run with docker-compose:

   docker-compose up
   

Connecting to Cursor AI

To connect this MCP server to Cursor AI:

1. Open Cursor settings
2. Navigate to MCP settings
3. Add a new MCP server with the following configuration:

For local Node.js:

{
  "mcpServers": {
    "startinfinity": {
      "command": "node",
      "args": ["/path/to/startinfinity-mcp-server/dist/index.js"],
      "env": {
        "STARTINFINITY_API_TOKEN": "your_api_token_here",
        "STARTINFINITY_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

For Docker:

{
  "mcpServers": {
    "startinfinity": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARTINFINITY_API_TOKEN=your_api_token_here",
        "-e", "STARTINFINITY_WORKSPACE_ID=your_workspace_id_here",
        "startinfinity-mcp-server:latest"
      ]
    }
  }
}

For docker-compose:

{
  "mcpServers": {
    "startinfinity": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/docker-compose.yml",
        "run", "--rm",
        "startinfinity-mcp-server"
      ],
      "env": {
        "STARTINFINITY_API_TOKEN": "your_api_token_here",
        "STARTINFINITY_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

Replace /path/to/startinfinity-mcp-server with the actual path to this project directory.

Basic Usage

Environment Variables

Required:

• STARTINFINITY_API_TOKEN - Your StartInfinity API token (obtain from your profile page)
• STARTINFINITY_WORKSPACE_ID - Your workspace ID (required, must be set in environment)

Note: The workspaceId parameter has been removed from all tools. The workspace ID is now always taken from the STARTINFINITY_WORKSPACE_ID environment variable.

Common Workflows

1. Fetching Items by Status

{
  "tool": "fetch_items_by_attribute",
  "arguments": {
    "boardId": "LA1dW8i1TTK",
    "attributeName": "Status",
    "attributeValue": "Doing"
  }
}

2. Creating a New Item

{
  "tool": "create_item",
  "arguments": {
    "boardId": "LA1dW8i1TTK",
    "folderId": "folder_id_here",
    "values": {
      "54767acf-0832-4080-839c-5556bbbd9f10": "Item Name",
      "attribute_id_2": "value_2"
    }
  }
}

3. Posting a Comment

{
  "tool": "post_comment",
  "arguments": {
    "boardId": "LA1dW8i1TTK",
    "itemId": "item_id_here",
    "content": "This is a comment"
  }
}

4. Getting Formatted Items

{
  "tool": "fetch_items_formatted",
  "arguments": {
    "boardId": "LA1dW8i1TTK",
    "folderId": "optional_folder_id",
    "includeSummary": true
  }
}

Tool Reference

Fetch Dashboard

Returns workspace information.

Input:

{}

Fetch Boards

Lists all boards in a workspace.

Input:

{}

Fetch Board

Gets detailed information about a specific board.

Input:

{
  "boardId": "LA1dW8i1TTK"
}

Fetch Folders

Lists all folders in a board.

Input:

{
  "boardId": "LA1dW8i1TTK"
}

Fetch Items

Lists items from a board with optional filtering.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "folderId": "optional_folder_id",
  "limit": 50,
  "before": "optional_cursor",
  "after": "optional_cursor"
}

Fetch Items by Attribute

Fetches items filtered by a specific attribute name and value.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "attributeName": "Status",
  "attributeValue": "Doing",
  "folderId": "optional_folder_id",
  "limit": 50
}

Fetch Item Details

Gets detailed information about a specific item.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "itemId": "item_id_here"
}

Update Item

Updates attributes of an existing item.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "itemId": "item_id_here",
  "values": {
    "attribute_id_1": "new_value_1",
    "attribute_id_2": "new_value_2"
  }
}

Fetch View

Gets view configuration for a specific view.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "viewId": "view_id_here"
}

Fetch Attributes

Lists all attributes for a board to understand the attribute structure.

Input:

{
  "boardId": "LA1dW8i1TTK"
}

Fetch Members

Lists all members in a workspace to map member IDs to names.

Input:

{}

Fetch Items Formatted

Fetches items with formatted attributes and titles for reporting.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "folderId": "optional_folder_id",
  "limit": 50,
  "includeSummary": true
}

Post Comment

Creates a comment on a specific item.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "itemId": "item_id_here",
  "content": "This is a comment"
}

Fetch Folder Snapshot

Provides a snapshot report of items in progress and pending in a folder.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "folderName": "Folder Name",
  "folderId": "optional_folder_id"
}

Fetch Item JSON

Fetches all available data for an item as JSON with attribute names as keys.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "itemId": "item_id_here"
}

Create Item

Creates a new item in a board folder.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "folderId": "folder_id_here",
  "values": {
    "attribute_id": "value"
  }
}

Delete Item

Deletes (archives) an item from a board.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "itemId": "item_id_here"
}

Create Folder

Creates a new folder in a board.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "name": "Folder Name",
  "parentId": "optional_parent_folder_id"
}

Delete Folder

Deletes a folder from a board.

Input:

{
  "boardId": "LA1dW8i1TTK",
  "folderId": "folder_id_here"
}

Create Board

Creates a new board in a workspace.

Input:

{
  "name": "Board Name",
  "description": "Optional description"
}

Delete Board

Deletes a board from a workspace.

Input:

{
  "boardId": "board_id_here"
}

Development

Running in Development Mode

For development with auto-rebuild:

npm run dev

In another terminal:

npm start

Testing

The project includes a comprehensive test suite with a mock API server.

Run tests:

npm test

Run tests with coverage:

npm run test:coverage

Run tests in watch mode:

npm run test:watch

Run tests in Docker:

# Start mock API server
docker-compose up -d mock-api

# Run tests
docker-compose run --rm --entrypoint sh startinfinity-mcp-server -c "npm install --include=dev && npm test"

API Documentation

For detailed information about the StartInfinity API, refer to: https://devdocs.startinfinity.com/2025-12-01.morava/

Rate Limiting

The StartInfinity API has a rate limit of 180 requests per minute. The server will return an error message if the rate limit is exceeded.

Error Handling

The server handles various error scenarios:

• Missing or invalid API tokens
• Missing required parameters
• Missing STARTINFINITY_WORKSPACE_ID environment variable
• API rate limiting (429 errors)
• Network errors
• Invalid API responses

All errors are returned in a user-friendly format.

License

MIT