Nestr

The MCP (Model Context Protocol) server from Nestr enables AI assistants to interact with your workspace, letting you search, create and organize nests, view structure, access insights, and collaborate on tasks and projects from within the AI interface.

How to use

You can connect your AI assistant to the MCP server in two primary ways: via the hosted HTTP endpoint or by running the MCP server locally as a stdio (local) process. The HTTP option provides a remote MCP URL for your client to call, while the local option runs the server on your machine using an executable command. Once connected, you can ask your AI assistant to list workspaces, search for nests, create or update nests, view circles and roles, retrieve insights, and add comments to nests.

Practical usage patterns include asking for workspaces you can access, searching for tasks related to a topic, creating new nests (projects or tasks), checking statuses of current projects, and assigning or inspecting ownership and accountability within your organization.

How to install

Prerequisites: Node.js and npm must be installed on your machine. You will either run the MCP server remotely or install and run it locally.

Option A: Use the hosted HTTP MCP endpoint

Option B: Run the MCP server locally with npm

# Install dependencies and run the server locally using npm and npx
npx @nestr/mcp

If you prefer to configure the MCP server for your client explicitly, you can include it in your client configuration as shown below.

{
  "mcpServers": {
    "nestr": {
      "command": "npx",
      "args": ["-y", "@nestr/mcp"],
      "env": {
        "NESTR_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuration and usage notes

Authentication can be performed via OAuth through the hosted service or by using an API key for local usage. Ensure you only grant permissions appropriate to the authenticated user.

If you run the local MCP server, supply your API key in the environment when starting the process. The example configuration shows using NESTR_API_KEY for local runs.

Environment variables

The following environment variables are used when running the MCP server locally or configuring clients.

• NESTR_API_KEY: Nestr API key with workspace access (used for local usage).

• NESTR_OAUTH_TOKEN: OAuth token that respects user permissions (alternative to API key).

• NESTR_API_BASE: API base URL (default: https://app.nestr.io/api).

Security

Do not commit your API key or OAuth token to version control. Use OAuth for granular permissions and rotate credentials if you suspect a breach.

Development

To contribute or run in development mode, follow the steps to clone, install, and run in development or HTTP server mode.

# Development workflow
git clone https://github.com/nestr-dev/nestr-mcp.git
cd nestr-mcp
npm install
export NESTR_API_KEY=your-api-key
npm run dev
# Or run the HTTP server variant for local testing
npm run dev:http

Build for production and test with the MCP Inspector as described in the development flow.

Available tools

nestr_list_workspaces

List accessible workspaces

nestr_get_workspace

Get workspace details

nestr_create_workspace

Create a new workspace (OAuth only)

nestr_search

Search for nests (tasks, projects, roles)

nestr_get_nest

Get details of a specific nest

nestr_get_nest_children

Get child nests

nestr_create_nest

Create a new nest

nestr_update_nest

Update nest properties

nestr_delete_nest

Delete a nest

nestr_reorder_nest

Reorder a nest relative to another

nestr_bulk_reorder

Bulk reorder multiple nests

nestr_add_comment

Add a comment to a nest

nestr_get_comments

Get comments/discussion on a nest

nestr_list_circles

List organizational circles

nestr_get_circle

Get circle details

nestr_get_circle_roles

Get roles in a circle

nestr_list_roles

List all roles

nestr_list_users

List workspace members

nestr_get_user

Get user details

nestr_list_labels

List workspace labels

nestr_get_label

Get label details

nestr_get_projects

List projects with status

nestr_get_insights

Get workspace metrics

nestr_get_insight_history

Get historical trend data for a metric

nestr_get_workspace_apps

List enabled apps/features

nestr_list_inbox

List items in user's inbox

nestr_create_inbox_item

Quick capture to inbox

nestr_get_inbox_item

Get inbox item details

nestr_update_inbox_item

Update inbox item

nestr_reorder_inbox

Reorder inbox items

nestr_list_personal_labels

List user's personal labels

nestr_create_personal_label

Create a personal label

nestr_get_daily_plan

Get items marked for today