🚀 Greptile MCP Server - TypeScript Edition

A modern, TypeScript-powered MCP (Model Context Protocol) server that provides AI-powered code search and querying capabilities through the Greptile API. Built with the official MCP SDK and designed for seamless integration with AI tools like Claude Desktop, Continue, and other MCP-compatible clients.

✨ Features

🔥 Zero-Installation Experience

# Start immediately with npx - no setup required!
npx greptile-mcp-server --api-key=xxx --github-token=yyy

🧠 AI-Powered Code Understanding

Natural Language Queries: Ask questions about codebases in plain English
Deep Code Analysis: Understand architecture, patterns, and implementation details
Cross-Repository Insights: Compare patterns and approaches across multiple codebases
Session Continuity: Build understanding progressively through conversation

⚡ Modern Architecture

Official MCP SDK: Built with TypeScript MCP SDK for full protocol compliance
Streaming Support: Real-time responses with Server-Sent Events
Type Safety: Full TypeScript integration with comprehensive type definitions
Plugin Architecture: Extensible design for custom tools and integrations

🛠️ Developer Experience

NPX Ready: Install and run with a single command
Auto-Configuration: Intelligent configuration detection and validation
Interactive Setup: Guided setup wizard for first-time users
Comprehensive Help: Built-in documentation and usage examples

🚀 Quick Start

Prerequisites

Node.js 18+ (for optimal performance)
Greptile API Key - Get yours at app.greptile.com
GitHub Token - Generate at github.com/settings/tokens with repo permissions

Instant Start

# Start immediately (will prompt for credentials if not set)
npx greptile-mcp-server

# With inline credentials
npx greptile-mcp-server --api-key=your_key --github-token=your_token

# Interactive setup wizard
npx greptile-mcp-server init

# Test connectivity
npx greptile-mcp-server test

Environment Setup

Option 1: .env File (Recommended for local development)

Create a .env file in your project root:

GREPTILE_API_KEY=your_greptile_api_key_here
GITHUB_TOKEN=your_github_personal_access_token_here
GREPTILE_BASE_URL=https://api.greptile.com/v2  # Optional

Option 2: System Environment Variables

Linux/macOS (Bash/Zsh):

# Current session
export GREPTILE_API_KEY="your_api_key_here"
export GITHUB_TOKEN="your_github_token_here"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GREPTILE_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export GITHUB_TOKEN="your_github_token_here"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell:

# Current session
$env:GREPTILE_API_KEY="your_api_key_here"
$env:GITHUB_TOKEN="your_github_token_here"

# Permanent
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"
# Note: Restart terminal after using setx

Windows Command Prompt:

# Current session
set GREPTILE_API_KEY=your_api_key_here
set GITHUB_TOKEN=your_github_token_here

# Permanent
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"

API Key and Token Setup

Greptile API Key:

Visit Greptile Settings
Generate a new API key
Copy the key to your environment

GitHub Token:

Visit GitHub Settings > Personal Access Tokens
Create a "Fine-grained personal access token" for better security
Grant repo permissions for repositories you want to index
Copy the token to your environment

🔧 MCP Client Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "greptile": {
      "command": "npx",
      "args": ["greptile-mcp-server"],
      "env": {
        "GREPTILE_API_KEY": "your_api_key",
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Continue IDE Extension

Add to your Continue configuration:

{
  "contextProviders": [
    {
      "name": "greptile-mcp",
      "type": "mcp",
      "serverName": "greptile",
      "command": ["npx", "greptile-mcp-server"]
    }
  ]
}

Other MCP Clients

The server uses standard MCP protocol and works with any MCP-compatible client:

# Generic MCP client connection
your-mcp-client connect --command "npx greptile-mcp-server"

🛠️ Available Tools

1. `greptile_help`

Get comprehensive documentation and usage examples.

{
  "name": "greptile_help"
}

2. `index_repository`

Index a repository to make it searchable.

{
  "name": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main",
    "reload": true
  }
}

3. `query_repository`

Query repositories with natural language.

{
  "name": "query_repository",
  "arguments": {
    "query": "How is authentication implemented in this codebase?",
    "repositories": [
      {
        "remote": "github",
        "repository": "microsoft/vscode", 
        "branch": "main"
      }
    ],
    "stream": false,
    "session_id": "optional-session-id"
  }
}

4. `get_repository_info`

Get information about indexed repositories.

{
  "name": "get_repository_info",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

📖 Usage Examples

Basic Workflow

# 1. Start the server
npx greptile-mcp-server

# 2. In your MCP client, index a repository
{
  "tool": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

# 3. Query the codebase
{
  "tool": "query_repository", 
  "arguments": {
    "query": "How does VS Code handle file watching?",
    "repositories": [{"remote": "github", "repository": "microsoft/vscode", "branch": "main"}]
  }
}

Advanced Session-Based Exploration

// Start with architecture overview
const session = "exploration-session-1";

// Query 1: High-level understanding
{
  "tool": "query_repository",
  "arguments": {
    "query": "What is the overall architecture of this codebase?",
    "session_id": session,
    "repositories": [...]
  }
}

// Query 2: Deep dive (builds on previous context)
{
  "tool": "query_repository", 
  "arguments": {
    "query": "How do the main components we just discussed interact with each other?",
    "session_id": session  // Same session for continuity
  }
}

// Query 3: Implementation details
{
  "tool": "query_repository",
  "arguments": {
    "query": "Show me the specific implementation of the component interaction patterns",
    "session_id": session
  }
}

🔀 Migration from Python Version

The TypeScript version maintains full compatibility with the Python implementation while adding significant improvements:

What's New

✅ Official MCP SDK: Standards-compliant implementation
✅ NPX Distribution: Zero-installation experience
✅ Better Performance: V8 engine advantages for I/O operations
✅ Type Safety: Full TypeScript integration
✅ Modern Tooling: ESLint, Prettier, comprehensive testing
✅ Enhanced CLI: Interactive setup and better UX

Migration Steps

# Old Python usage
python -m src.main

# New TypeScript usage  
npx greptile-mcp-server

# Same MCP tools and API compatibility
# No changes needed in MCP client configurations

🚨 Troubleshooting

Testing Your Setup

Always test your configuration after setup:

npx greptile-mcp-server test

Common Issues

❌ "Environment variables missing"

Problem: Server can't find your API keys Solutions:

Restart your terminal after setting permanent environment variables

Verify environment variables are set:

# Linux/macOS
echo $GREPTILE_API_KEY
echo $GITHUB_TOKEN

# Windows PowerShell
echo $env:GREPTILE_API_KEY
echo $env:GITHUB_TOKEN

Try using inline credentials:

GREPTILE_API_KEY="your_key" GITHUB_TOKEN="your_token" npx greptile-mcp-server

❌ "GitHub token validation failed"

Problem: GitHub token is invalid or has insufficient permissions Solutions:

Ensure your token has repo permissions
Generate a new token at GitHub Settings
For better security, use "Fine-grained personal access tokens"
Check token hasn't expired

❌ "Greptile API authentication failed"

Problem: Greptile API key is invalid or expired Solutions:

Get a new API key from Greptile Settings
Verify the key is correctly copied (no extra spaces)
Check if your API key has expired

❌ "Cannot find module" or import errors

Problem: NPX cache issues or incomplete installation Solutions:

Clear NPX cache: npx clear-npx-cache
Force fresh install: npx greptile-mcp-server@latest
Check Node.js version (requires Node 18+)

❌ MCP client connection issues

Problem: Claude Desktop or other MCP client can't connect Solutions:

Verify MCP server configuration syntax
Check Claude Desktop logs for detailed error messages
Ensure environment variables are accessible to the MCP client
Try running the server manually first to verify it works

Getting Help

Run npx greptile-mcp-server init for interactive setup
Run npx greptile-mcp-server test for detailed diagnostics
Check the Greptile Documentation for API-specific issues
Visit MCP Documentation for client integration help

❓ Frequently Asked Questions

Q: Do I need to install anything locally to use this?

A: No! The server runs via NPX with zero installation required. Just run npx greptile-mcp-server and it will download and run automatically.

Q: Can I use this with any MCP-compatible client?

A: Yes! This server implements the standard Model Context Protocol and works with Claude Desktop, MCP CLI tools, and any other MCP-compatible client.

Q: How do I index private repositories?

A: Ensure your GitHub token has repo permissions for private repositories. The token needs access to read the repositories you want to index.

Q: What's the difference between .env files and environment variables?

.env files are great for local development - they only work in the directory where the file exists
Environment variables are system-wide and work everywhere, making them better for global usage with npx

Q: How much does it cost to use Greptile?

A: Greptile pricing depends on your usage. Check Greptile's pricing page for current rates. This MCP server itself is free and open-source.

Q: Can I use this with multiple repositories?

A: Yes! You can index multiple repositories and query across all of them. Use the index_repository tool for each repository you want to add.

Q: How long does it take to index a repository?

A: Indexing time varies by repository size. Small repos (< 1000 files) typically take 1-2 minutes, while larger repos may take 10-15 minutes. You can check status with the get_repository_info tool.

Q: Is my code data secure?

A: Your code is processed by Greptile's API according to their security and privacy policies. Check Greptile's security documentation for details about data handling and retention.

Q: Can I run this on Windows?

A: Yes! The server works on Windows, macOS, and Linux. Use the platform-specific environment variable setup instructions above.

Q: Why do I get "command not found" errors?

A: This usually means:

NPX is not installed (install Node.js which includes NPX)
Your PATH doesn't include Node.js binaries
There's a typo in the command (it's npx greptile-mcp-server not npx @greptile/mcp-server)

🏗️ Development

Local Development

# Clone and setup
git clone https://github.com/greptile/mcp-server.git
cd mcp-server
npm install

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting and formatting
npm run lint
npm run format

Project Structure

src/
├── cli.ts              # NPX CLI interface
├── server.ts           # Core MCP server implementation  
├── index.ts            # Module exports
├── clients/
│   └── greptile.ts     # Greptile API client
├── types/
│   └── index.ts        # TypeScript type definitions
└── utils/
    └── index.ts        # Utility functions

tests/
├── unit/               # Unit tests
└── integration/        # Integration tests

Build Configuration

TypeScript: ES2022 target with strict mode
Build Tool: tsup for dual ESM/CJS output
Testing: Mocha + Chai with TypeScript support
Code Quality: ESLint + Prettier with TypeScript rules

🔧 Configuration Options

CLI Arguments

npx greptile-mcp-server \
  --api-key="your_key" \
  --github-token="your_token" \
  --base-url="https://api.greptile.com/v2" \
  --repositories='[{"remote":"github","repository":"owner/repo","branch":"main"}]' \
  --stream=true \
  --timeout=60000 \
  --verbose

Environment Variables

Variable	Description	Default
`GREPTILE_API_KEY`	Greptile API key	Required
`GITHUB_TOKEN`	GitHub personal access token	Required
`GREPTILE_BASE_URL`	API base URL	`https://api.greptile.com/v2`

Configuration File (Optional)

Create greptile.config.js:

export default {
  apiKey: process.env.GREPTILE_API_KEY,
  githubToken: process.env.GITHUB_TOKEN,
  repositories: [
    { remote: 'github', repository: 'owner/repo', branch: 'main' }
  ],
  features: {
    streaming: true,
    orchestration: true,
    flowEnhancement: true
  }
};

🚀 Deployment

Smithery Cloud Deployment

Deploy instantly to Smithery with zero configuration:

# Install Smithery CLI
npm install -g smithery

# Deploy from repository
smithery deploy

# Or deploy with custom configuration
smithery deploy --config smithery.yaml

# Monitor deployment
smithery status
smithery logs

Docker Deployment

# Build Docker image
docker build -t greptile-mcp .

# Run with environment variables
docker run -e GREPTILE_API_KEY=your_key \
           -e GITHUB_TOKEN=your_token \
           -p 8080:8080 \
           greptile-mcp

# Or build Smithery-optimized image
npm run smithery:build

Environment Variables for Deployment

# Required
GREPTILE_API_KEY=your_greptile_api_key
GITHUB_TOKEN=your_github_token

# Optional
GREPTILE_BASE_URL=https://api.greptile.com/v2
TRANSPORT=stdio
HOST=0.0.0.0
PORT=8080

Cloud Platforms

Smithery: One-click deployment with smithery deploy
Railway: Connect GitHub repo, set environment variables
Render: Use npm start as start command
Heroku: Standard Node.js deployment
DigitalOcean App Platform: Docker or buildpack deployment

🚦 Performance & Benchmarks

Startup Performance

Cold Start: < 2 seconds
Memory Usage: ~50MB base footprint
Concurrent Requests: Handles 100+ concurrent MCP tool calls

API Performance

Query Response: Typically 1-3 seconds
Streaming: Real-time chunk delivery
Repository Indexing: Varies by repository size (usually 30s-5min)

Compared to Python Version

40% Faster Startup - V8 vs Python runtime
60% Smaller Container - Node.js vs Python base images
30% Better Memory Efficiency - V8 garbage collection
Native Streaming - Better SSE performance

🛡️ Security & Best Practices

Token Security

Environment Variables: Store tokens in environment, not code
Minimal Permissions: Use GitHub tokens with only required repo permissions
Token Rotation: Regularly rotate API keys and tokens
Local Storage: Never commit tokens to version control

Network Security

HTTPS Only: All API communications use HTTPS
Request Validation: Input validation and sanitization
Rate Limiting: Built-in retry logic with exponential backoff
Error Handling: Comprehensive error handling without token exposure

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Run the test suite (npm test)
Ensure code quality (npm run lint)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Anthropic for the Model Context Protocol specification
Greptile for the powerful code analysis API
TypeScript Community for excellent tooling and ecosystem
MCP Community for protocol development and feedback

📞 Support

Documentation: docs.greptile.com
Issues: GitHub Issues
Discussions: GitHub Discussions
Discord: MCP Community Discord

Built with ❤️ by the Greptile team • Powered by TypeScript and the Model Context Protocol

greptile-mcp

README Documentation