MCP server exposing Auggie CLI for codebase context retrieval
npm install auggie-context-mcp

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.
This MCP server is designed to be used with MCP clients like Claude Desktop or Cursor. It cannot be used standalone.
1. Install Auggie CLI: https://docs.augmentcode.com/cli/overview
2. Authenticate with Auggie:
``bash`
auggie login
This opens a browser for authentication. Once logged in, you're ready to go!
1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
2. Add this configuration:
`json`
{
"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.
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.
- š 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
- 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)
The server supports two authentication methods:
Simply log in using the Auggie CLI:
`bash`
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!
Alternatively, you can provide an explicit access token via the AUGMENT_SESSION_AUTH environment variable.
Get Your Token:
`bash1. Ensure Auggie CLI is installed
auggie --version
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:
`json
{
"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:
`bash
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
`$3
- 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.
$3
Add to your Cursor MCP config (
.cursor/mcp.json - global or per-project):Simple setup (uses your Auggie CLI login):
`json
{
"mcpServers": {
"auggie-context": {
"command": "npx",
"args": ["-y", "auggie-context-mcp@latest"]
}
}
}
`With explicit token (optional):
`json
{
"mcpServers": {
"auggie-context": {
"command": "npx",
"args": ["-y", "auggie-context-mcp@latest"],
"env": {
"AUGMENT_SESSION_AUTH": "{\"accessToken\":\"your-token-here\",\"tenantURL\":\"https://...\",\"scopes\":[\"read\",\"write\"]}"
}
}
}
}
`$3
Edit
~/Library/Application Support/Claude/claude_desktop_config.json:Simple setup (uses your Auggie CLI login):
`json
{
"mcpServers": {
"auggie-context": {
"command": "npx",
"args": ["-y", "auggie-context-mcp@latest"]
}
}
}
`With explicit token (optional):
`json
{
"mcpServers": {
"auggie-context": {
"command": "npx",
"args": ["-y", "auggie-context-mcp@latest"],
"env": {
"AUGMENT_SESSION_AUTH": "{\"accessToken\":\"your-token-here\",\"tenantURL\":\"https://...\",\"scopes\":[\"read\",\"write\"]}"
}
}
}
}
`$3
Edit
%APPDATA%\Claude\claude_desktop_config.json:Simple setup (uses your Auggie CLI login):
`json
{
"mcpServers": {
"auggie-context": {
"command": "npx",
"args": ["-y", "auggie-context-mcp@latest"]
}
}
}
`With explicit token (optional):
`json
{
"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
$3
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: textExample 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
$3
`bash
Clone the repository
git clone https://github.com/aj47/auggie-mcp.git
cd auggie-mcpInstall dependencies
npm installBuild
npm run build
`$3
`bash
Watch mode (auto-rebuild on changes)
npm run watchRun in development
npm run dev
`$3
`bash
Build the project
npm run buildMake sure you're logged in to Auggie
auggie loginTest with MCP Inspector (recommended)
npx @modelcontextprotocol/inspector node dist/index.jsOr 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:
`bash
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
$3
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$3
The server cannot find the Auggie CLI. Ensure it's installed and on your PATH:
`bash
auggie --version
`If not found, install from: https://docs.augmentcode.com/cli/overview
$3
The Auggie CLI needs authentication. You have two options:
Option 1: Use Auggie CLI login (recommended)
`bash
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)$3
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.
$3
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 listSecurity
- Read-only: This server only queries codebases; it cannot modify files
- Token safety: Never commit
AUGMENT_SESSION_AUTH` to version controlMIT
Contributions are welcome! Please feel free to submit a Pull Request.
- Augment Code
- Auggie CLI Documentation
- Model Context Protocol
- MCP Specification