Auggie Context MCP Server

A Model Context Protocol (MCP) server that exposes Auggie CLI for codebase context retrieval. This allows AI agents like Claude, Cursor, and others to query codebases using Augment's powerful context engine.

Quick Start

This MCP server is designed to be used with MCP clients like Claude Desktop or Cursor. It cannot be used standalone.

Prerequisites

1. Install Auggie CLI: https://docs.augmentcode.com/cli/overview
2. Authenticate with Auggie:

   auggie login

   This opens a browser for authentication. Once logged in, you're ready to go!

Setup with Claude Desktop

1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
2. Add this configuration:

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"]
    }
  }
}

3. Restart Claude Desktop
4. You should now see the query_codebase tool available in Claude

Note: If you need to use a specific token instead of your Auggie CLI login, you can add an env section with AUGMENT_SESSION_AUTH. See the Authentication section for details.

Setup with Cursor

1. Create or edit .cursor/mcp.json in your project or globally
2. Add the same configuration as above
3. Restart Cursor

See Installation & Usage section for detailed instructions.

Features

• 🔍 Codebase Query: Intelligent Q&A over repositories using Augment's context engine
• 🚀 Simple Setup: Pure TypeScript/Node.js implementation (no Python required)
• 🔒 Read-Only: Safe context retrieval without file modification capabilities
• ⚡ Fast: Direct integration with Auggie CLI
• 📦 Easy Distribution: Single npm package, works with npx

Requirements

• Node.js 18+
• Auggie CLI installed and available on PATH
  • Install: See Auggie CLI installation guide
  • Verify: auggie --version
• Augment Authentication (see Authentication section below)

Authentication

The server supports two authentication methods:

Option 1: Auggie CLI Login (Recommended)

Simply log in using the Auggie CLI:

auggie login

This opens a browser for authentication. Once logged in, the MCP server will automatically use your Auggie CLI session. No additional configuration needed!

Option 2: Environment Variable (AUGMENT_SESSION_AUTH)

Alternatively, you can provide an explicit access token via the AUGMENT_SESSION_AUTH environment variable.

Get Your Token:

# 1. Ensure Auggie CLI is installed
auggie --version

# 2. Sign in to Augment (opens browser)
auggie login

# 3. Print your access token
auggie token print

This will output something like:

TOKEN={"accessToken":"your-token-here","tenantURL":"https://...","scopes":["read","write"]}

Set the Token in MCP client config:

Add the token to your MCP client configuration:

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"],
      "env": {
        "AUGMENT_SESSION_AUTH": "{\"accessToken\":\"your-token-here\",\"tenantURL\":\"https://...\",\"scopes\":[\"read\",\"write\"]}"
      }
    }
  }
}

Or set in shell environment:

# Get your token
TOKEN=$(auggie token print | grep '^TOKEN=' | cut -d= -f2-)

# One-time for current session
export AUGMENT_SESSION_AUTH="$TOKEN"

# Or persist in ~/.zshrc or ~/.bashrc
echo "export AUGMENT_SESSION_AUTH='$TOKEN'" >> ~/.zshrc
source ~/.zshrc

Which Method Should I Use?

• Use Auggie CLI Login if you're the only user on your machine and want the simplest setup
• Use AUGMENT_SESSION_AUTH if you need to use a specific token or are in a shared/CI environment

⚠️ Security: Never commit tokens to source control. Use environment variables or secure config stores.

Installation & Usage

Note: This server is designed to be used with MCP clients (Claude Desktop, Cursor, etc.). It uses the MCP protocol over stdio and cannot be run standalone.

Cursor Configuration

Add to your Cursor MCP config (.cursor/mcp.json - global or per-project):

Simple setup (uses your Auggie CLI login):

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"]
    }
  }
}

With explicit token (optional):

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"],
      "env": {
        "AUGMENT_SESSION_AUTH": "{\"accessToken\":\"your-token-here\",\"tenantURL\":\"https://...\",\"scopes\":[\"read\",\"write\"]}"
      }
    }
  }
}

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Simple setup (uses your Auggie CLI login):

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"]
    }
  }
}

With explicit token (optional):

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"],
      "env": {
        "AUGMENT_SESSION_AUTH": "{\"accessToken\":\"your-token-here\",\"tenantURL\":\"https://...\",\"scopes\":[\"read\",\"write\"]}"
      }
    }
  }
}

Claude Desktop (Windows)

Edit %APPDATA%\Claude\claude_desktop_config.json:

Simple setup (uses your Auggie CLI login):

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"]
    }
  }
}

With explicit token (optional):

{
  "mcpServers": {
    "auggie-context": {
      "command": "npx",
      "args": ["-y", "auggie-context-mcp@latest"],
      "env": {
        "AUGMENT_SESSION_AUTH": "{\"accessToken\":\"your-token-here\",\"tenantURL\":\"https://...\",\"scopes\":[\"read\",\"write\"]}"
      }
    }
  }
}

Available Tools

query_codebase

Query a codebase using Augment's context engine.

Parameters:

• query (required): The question or query about the codebase
• workspace_root (optional): Absolute path to the workspace/repository root. Defaults to current directory.
• model (optional): Model ID to use. Example: claude-3-5-sonnet-20241022
• rules_path (optional): Path to additional rules file
• timeout_sec (optional): Query timeout in seconds. Default: 240
• output_format (optional): Output format (text or json). Default: text

Example Usage in Claude/Cursor:

What is the architecture of this codebase?

How does the authentication system work?

Where is the user registration logic implemented?

Show me how the payment processing is handled.

Development

Setup

# Clone the repository
git clone https://github.com/aj47/auggie-mcp.git
cd auggie-mcp

# Install dependencies
npm install

# Build
npm run build

Development Mode

# Watch mode (auto-rebuild on changes)
npm run watch

# Run in development
npm run dev

Testing Locally

# Build the project
npm run build

# Make sure you're logged in to Auggie
auggie login

# Test with MCP Inspector (recommended)
npx @modelcontextprotocol/inspector node dist/index.js

# Or test with a real MCP client (Claude Desktop, Cursor)
# by pointing it to your local build instead of npx

Optional: If you want to test with an explicit token instead of your Auggie CLI login:

export AUGMENT_SESSION_AUTH=$(auggie token print | grep '^TOKEN=' | cut -d= -f2-)
npx @modelcontextprotocol/inspector node dist/index.js

Architecture

┌─────────────────────┐
│   AI Agent          │
│ (Claude, Cursor)    │
└──────────┬──────────┘
           │ MCP Protocol (stdio)
           ▼
┌─────────────────────┐
│ auggie-context-mcp  │
│  (TypeScript/Node)  │
│                     │
│  Tool:              │
│  - query_codebase   │
└──────────┬──────────┘
           │ subprocess
           ▼
┌─────────────────────┐
│   Auggie CLI        │
│  --print --quiet    │
│                     │
│  Augment Context    │
│  Engine             │
└─────────────────────┘

Troubleshooting

Server not showing up in Claude/Cursor

1. Check config file syntax: Ensure your JSON is valid (no trailing commas, proper quotes)
2. Verify authentication: Make sure you've run auggie login or set AUGMENT_SESSION_AUTH in the config
3. Restart the client: Completely quit and restart Claude Desktop or Cursor
4. Check logs:
   • Claude Desktop (macOS): ~/Library/Logs/Claude/mcp*.log
   • Claude Desktop (Windows): %APPDATA%\Claude\logs\mcp*.log
   • Cursor: Check MCP logs in settings

"Auggie CLI not found"

The server cannot find the Auggie CLI. Ensure it's installed and on your PATH:

auggie --version

If not found, install from: https://docs.augmentcode.com/cli/overview

"Authentication required" or "not logged in"

The Auggie CLI needs authentication. You have two options:

Option 1: Use Auggie CLI login (recommended)

auggie login

Option 2: Set explicit token in MCP config

1. Run auggie token print to get your token
2. Copy the entire JSON value (everything after TOKEN=)
3. Add it to the env section in your MCP config (see examples above)

"Query timed out"

For large codebases, queries may take longer. The default timeout is 240 seconds (4 minutes). If you need more time, you can't currently configure this in the MCP client config, but you can modify the source code and rebuild.

Tool not appearing in Claude/Cursor

1. Verify the server is configured correctly in your MCP config
2. Check that the config file is in the correct location
3. Restart the client application
4. Look for the query_codebase tool in the available tools list

Security

• Read-only: This server only queries codebases; it cannot modify files
• Token safety: Never commit AUGMENT_SESSION_AUTH to version control
• Workspace isolation: Queries are scoped to the specified workspace

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• Augment Code
• Auggie CLI Documentation
• Model Context Protocol
• MCP Specification