@nestr/mcp

MCP (Model Context Protocol) server for Nestr - connect AI assistants like Claude to your workspace.

What is this?

This MCP server allows AI assistants to interact with your Nestr workspace:

• Search for tasks, projects, and roles
• Create and update nests
• View organizational structure (circles, roles, accountabilities)
• Get workspace insights and metrics
• Add comments and collaborate

Quick Start

1. Get Your API Key

1. Go to your Nestr workspace
2. Click Settings (gear icon) in the top right
3. Go to the Integrations tab
4. Find "Workspace API access" and click Configure
5. Click "New API key" and copy it

2. Configure Your AI Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop after saving.

Claude Code

Add to your Claude Code MCP settings:

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

Cursor

Add to your Cursor MCP configuration with the same format as above.

3. Start Using It

Ask your AI assistant things like:

• "What workspaces do I have access to?"
• "Search for tasks related to marketing"
• "Create a new project called 'Q1 Planning'"
• "What are my current projects and their status?"
• "Who is responsible for customer support?"
• "Show me the structure of the Product circle"

Available Tools

Authentication

There are two ways to authenticate with the Nestr MCP server:

Option 1: API Key (Simple)

API keys provide full workspace access and are the easiest way to get started. See Quick Start above.

Note: API keys have full workspace access regardless of user permissions.

Option 2: OAuth (Recommended for Hosted Service)

OAuth authentication respects user-specific permissions - the AI assistant can only access what the authenticated user can access.

Using the Hosted Service (mcp.nestr.io)

The hosted service at mcp.nestr.io supports OAuth out of the box:

1. Visit mcp.nestr.io/oauth/authorize
2. Log in with your Nestr account and authorize access
3. Copy the access token from the success page
4. Use the token in your MCP client configuration:

{
  "mcpServers": {
    "nestr": {
      "command": "npx",
      "args": ["-y", "@nestr/mcp"],
      "env": {
        "NESTR_OAUTH_TOKEN": "your-oauth-token-here"
      }
    }
  }
}

Self-Hosted OAuth Setup

If you're running your own instance of the MCP server and want to enable OAuth:

1. Contact Nestr at dev@nestr.io to register an OAuth client
2. Provide your callback URL (e.g., https://your-domain.com/oauth/callback)
3. Nestr will provide you with a client_id and client_secret
4. Set the following environment variables:

NESTR_OAUTH_CLIENT_ID=your-client-id
NESTR_OAUTH_CLIENT_SECRET=your-client-secret

Once configured, users can authenticate via /oauth/authorize on your server.

Environment Variables

* Either NESTR_API_KEY or NESTR_OAUTH_TOKEN is required.

Development

# Clone the repository
git clone https://github.com/nestr-dev/nestr-mcp.git
cd nestr-mcp

# Install dependencies
npm install

# Set your API key
export NESTR_API_KEY=your-api-key

# Run in development mode (stdio)
npm run dev

# Run HTTP server for local testing
npm run dev:http

# Build for production
npm run build

# Test with MCP Inspector
npm run inspect

Hosted Service

A hosted version is available at mcp.nestr.io for users who prefer not to run the server locally.

Security

• Never commit your API key or OAuth token to version control
• API keys provide full workspace access - consider using OAuth for more granular permissions
• OAuth tokens respect user permissions and are the recommended approach for shared environments
• Store credentials securely (e.g., in a password manager or secrets manager)
• Rotate keys/tokens if you suspect they've been compromised

Resources

• Nestr Help Center
• Nestr API Documentation
• Model Context Protocol
• MCP Specification

License

MIT - see LICENSE

Support

• GitHub Issues
• Nestr Support