Package Exports
- ask-mcp
- ask-mcp/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ask-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Ask MCP 🤖
A powerful Model Context Protocol (MCP) server that provides seamless access to multiple state-of-the-art AI models through OpenRouter. Perfect for integration with Cursor, Claude Desktop, and other MCP-compatible clients.
✨ Features
- 🎯 5 Premium AI Models: Grok, Gemini 2.5 Pro, Kimi, Qwen3 Coder, GLM-4.5
- 💰 Free Tier Support: Access free variants when available
- 🔐 OAuth Authentication: Secure OpenRouter integration
- 🚀 Easy Setup: One-command OAuth configuration
- 🔌 MCP Compatible: Works with Cursor, Claude Desktop, and more
- 📦 TypeScript: Full type safety and modern development
Supported Models
- Grok: Advanced reasoning and analysis (x-ai/grok-4)
- Gemini 2.5 Pro: Google's latest multimodal AI (google/gemini-2.5-pro)
- Kimi: Efficient and fast responses (moonshotai/kimi-k2)
- Qwen 3 Coder: Specialized for coding tasks (qwen/qwen3-coder)
- GLM: General language model (z-ai/glm-4.5)
Free Model Variants
The tool supports free model variants for cost-effective usage:
- Kimi Free: moonshotai/kimi-k2:free
- Qwen Free: qwen/qwen3-coder:free
- GLM Free: z-ai/glm-4.5-air:free
Free models are automatically used as fallback when payment errors occur, or can be explicitly requested using the free
parameter.
Installation
Option 1: NPM Package (Recommended)
npm install -g ask-mcp
First-time setup: After installation, you'll need to authenticate with OpenRouter. You can either:
- Set your API key:
export OPENROUTER_API_KEY="your-key-here"
- Or use OAuth setup (from source):
npm run setup
and press ENTER when prompted
Option 2: From Source Installation
Clone and install:
git clone https://github.com/SerPepe/Ask-MCP cd ask-mcp npm install npm run build
Configure in your MCP client (see Configuration section below)
First-time setup: When you first use the MCP server, it will automatically prompt for OAuth authentication. You can also run the setup manually:
npm run setup
Option 3: Use Hosted Service
Deploy Ask-MCP to Cloudflare Workers for a hosted solution that doesn't require local installation.
Benefits:
- ✅ No local setup required
- ✅ Always available and up-to-date
- ✅ Automatic scaling
- ✅ Free tier available (100k requests/day)
Quick Deploy:
git clone https://github.com/SerPepe/Ask-MCP.git
cd Ask-MCP
npm install
wrangler login
wrangler secret put OPENROUTER_API_KEY
./deploy.sh
Configure Claude Desktop:
{
"mcpServers": {
"ask-mcp": {
"command": "npx",
"args": ["ask-mcp-client", "--host", "https://your-deployed-url.workers.dev"],
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key-here"
}
}
}
}
📖 Detailed deployment guide: See DEPLOYMENT.md
Quick Start
Option 1: NPM Installation (Recommended)
1. Install globally: npm install -g ask-mcp
2. Configure in your MCP client (Cursor/Claude Desktop)
3. First-time setup: When you first use the MCP server, it will automatically detect the missing API key and prompt you to authenticate with OpenRouter via OAuth. Simply press ENTER when prompted, and your browser will open automatically for secure authentication.
4. Start using the AI models!
Option 2: From Source with OAuth Setup (Auto-Authentication)
1. Clone the repository
2. Install dependencies: npm install
3. Run OAuth setup: npm run setup
4. Press ENTER when prompted (browser will auto-open for OpenRouter OAuth)
5. Complete authentication in browser
6. Test the server: npm test
Option 3: Manual API Key Setup
1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Set your OpenRouter API key: export OPENROUTER_API_KEY="your-key-here"
5. Test the server: npm test
Configuration
Authentication Options
The Ask MCP tool supports two authentication methods:
Option 1: API Key Authentication (Recommended)
- Sign up at OpenRouter
- Get your API key from the dashboard
- Add credits to your account
- Set the
OPENROUTER_API_KEY
environment variable
Option 2: OAuth Authentication
- Use the built-in OAuth flow for secure authentication
- Generate authorization URLs and exchange codes for API keys
- Perfect for applications requiring user consent
Configure MCP Client
For Cursor IDE
Option A: Using NPM Package (Recommended)
{
"mcpServers": {
"ask-mcp": {
"command": "ask-mcp"
}
}
}
Option B: Using Local Build
{
"mcpServers": {
"ask-mcp": {
"command": "node",
"args": ["/path/to/ask-mcp/dist/index.js"]
}
}
}
Option C: Manual API Key (Optional) If you prefer to set the API key manually instead of using OAuth:
{
"mcpServers": {
"ask-mcp": {
"command": "ask-mcp",
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key-here"
}
}
}
}
For Claude Desktop
Same configuration options as above work for Claude Desktop.
Usage
Once configured, you can use the following commands in your MCP client:
Ask Grok
ask-grok "What is the latest in AI development?"
Ask Gemini
ask-gemini "Explain quantum computing in simple terms"
Ask Kimi
ask-kimi "Write a Python function to sort a list"
Ask Qwen
ask-qwen "Debug this JavaScript code: console.log('hello world')"
Ask GLM
ask-glm "Translate this to Spanish: Hello, how are you?"
Each model has specific strengths:
- Use Grok for complex reasoning and analysis
- Use Gemini for multimodal tasks (text + images)
- Use Kimi for quick, efficient responses
- Use Qwen for coding and technical tasks
- Use GLM for general language tasks
Smart Fallback System
The tool includes intelligent error handling:
- Automatic Fallback: When payment/quota errors occur, the tool automatically retries with free model variants
- Manual Free Mode: Use the
free: true
parameter to directly use free models - Error Recovery: Comprehensive error messages help diagnose issues
With System Prompt
You can also provide a custom system prompt:
ask-grok {
"question": "What's the weather like?",
"system_prompt": "You are a helpful weather assistant. Always ask for location if not provided."
}
Using Free Models
You can explicitly use free model variants:
ask-kimi {
"question": "What is machine learning?",
"free": true
}
Usage Examples
Basic Usage
{
"name": "ask-grok",
"arguments": {
"question": "Explain quantum computing"
}
}
With Custom System Prompt
{
"name": "ask-gemini",
"arguments": {
"question": "Write a Python function to sort a list",
"system_prompt": "You are a senior Python developer. Provide clean, well-documented code."
}
}
Using Free Models
{
"name": "ask-kimi",
"arguments": {
"question": "What is machine learning?",
"free": true
}
}
GLM Model Usage
{
"name": "ask-glm",
"arguments": {
"question": "Translate this to Spanish: Hello, how are you?",
"system_prompt": "You are a professional translator."
}
}
OAuth Authentication
The Ask MCP tool includes built-in OAuth support for secure authentication with OpenRouter.
OAuth Tools
Generate Authorization URL
{
"name": "openrouter-auth-url",
"arguments": {
"redirect_uri": "http://localhost:8080/callback",
"state": "optional-security-state"
}
}
Exchange Authorization Code
{
"name": "openrouter-exchange-code",
"arguments": {
"code": "authorization-code-from-callback",
"state": "optional-security-state"
}
}
OAuth Flow
- Generate Authorization URL: Use
openrouter-auth-url
to get the OAuth URL - User Authorization: Visit the URL and authorize the application
- Get Authorization Code: Copy the code from the callback URL
- Exchange Code: Use
openrouter-exchange-code
to get your API key - Save API Key: Set the returned API key as
OPENROUTER_API_KEY
OAuth Environment Variables
# Optional OAuth configuration
export OPENROUTER_CLIENT_ID="your-client-id" # Optional
export OPENROUTER_CLIENT_SECRET="your-client-secret" # Optional
export OPENROUTER_REDIRECT_URI="http://localhost:8080/callback" # Default provided
Deployment
Cloudflare Workers (Recommended)
Deploy to Cloudflare Workers with Container support for scalable hosting:
# Install Wrangler CLI
npm install -g wrangler
# Login to Cloudflare
wrangler login
# Deploy container
wrangler deploy
Benefits:
- ✅ Serverless scaling
- ✅ Global edge deployment
- ✅ Cost-effective (Workers Paid plan)
- ✅ Built-in container support
Vercel Deployment
# Install Vercel CLI
npm install -g vercel
# Deploy
vercel
Docker Deployment
# Build container
docker build -t ask-mcp .
# Run container
docker run -p 3000:3000 -e OPENROUTER_API_KEY="your-key" ask-mcp
Development
Run in Development Mode
npm run dev
Build
npm run build
Start Production Server
npm start
Hosted Service
For users who prefer not to run the MCP server locally, we provide a hosted service option.
Benefits of Hosted Service
- No local installation required
- Always up-to-date with latest features
- Reduced resource usage on your machine
- Automatic scaling and reliability
Using Hosted Service
- Get the hosted endpoint: Contact us for the hosted service URL
- Configure your MCP client to use the hosted endpoint
- Add your OpenRouter API key in the configuration
Self-Hosting with Docker
You can also host your own instance using Docker:
# Clone the repository
git clone https://github.com/SerPepe/Ask-MCP
cd ask-mcp
# Build and run with Docker Compose
docker-compose up -d
The service will be available at http://localhost:3000
Troubleshooting
Common Issues
"OpenRouter API key not configured"
- Make sure you've set the
OPENROUTER_API_KEY
environment variable - Check that your API key is valid and has credits
- Make sure you've set the
"No response received from the model"
- Check your OpenRouter account has sufficient credits
- Verify the model is available on OpenRouter
Connection issues
- Ensure you have internet connectivity
- Check if OpenRouter API is accessible from your network
NPM package issues
- Try reinstalling:
npm uninstall -g ask-mcp && npm install -g ask-mcp
- Check Node.js version (requires Node.js 16+)
- Try reinstalling:
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.