Provides enhanced query and search capabilities for code repositories when the 'genius' parameter is enabled, offering improved contextual understanding
Allows accessing and indexing GitHub repositories for code search and querying, supporting both public and private repositories with appropriate authentication
Enables indexing and searching GitLab repositories, providing code search capabilities and repository information retrieval with proper authentication
🚀 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
🧠 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
Environment Setup
Option 1: .env File (Recommended for local development)
Create a .env
file in your project root:
Option 2: System Environment Variables
Linux/macOS (Bash/Zsh):
Windows PowerShell:
Windows Command Prompt:
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
:
Continue IDE Extension
Add to your Continue configuration:
Other MCP Clients
The server uses standard MCP protocol and works with any MCP-compatible client:
🛠️ Available Tools
1. greptile_help
Get comprehensive documentation and usage examples.
2. index_repository
Index a repository to make it searchable.
3. query_repository
Query repositories with natural language.
4. get_repository_info
Get information about indexed repositories.
📖 Usage Examples
Basic Workflow
Advanced Session-Based Exploration
🔀 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
🚨 Troubleshooting
Testing Your Setup
Always test your configuration after setup:
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:
- Try using inline credentials:
❌ "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?
A:
- .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
notnpx @greptile/mcp-server
)
🏗️ Development
Local Development
Project Structure
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
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
:
🚀 Deployment
Smithery Cloud Deployment
Deploy instantly to Smithery with zero configuration:
Docker Deployment
Environment Variables for Deployment
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
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
greptile-mcp
Related MCP Servers
- Apache 2.0
- Apache 2.0
- MIT License