OpenRouter MCP Client for Cursor

A Model Context Protocol (MCP) client tailored for Cursor that interfaces with OpenRouter.ai for broad access to numerous AI model endpoints.

Essential Prerequisites

• Runtime Environment: Node.js version 18.0.0 or newer is mandatory.
• Authentication Credential: A valid API token procured from openrouter.ai/keys is required.

Core Capabilities

• Establishes an MCP communication tunnel to OpenRouter.ai.
• Grants access to a comprehensive catalog of AI engines from providers like Google, Meta, DeepSeek, and others.
• Utilizes the defined MCP transport specification for interaction with the Cursor environment.
• Incorporates response and metadata caching to minimize redundant external service calls.
• Accommodates model utilization under both consumption-based and free-tier access structures.
• Features advanced utility for executing simultaneous prompts across several models to aggregate outputs.

Accessible Model Catalog

This specific gateway exposes the entire spectrum of models currently published on the OpenRouter platform, including but not limited to:

• Google Gemini 2.5 Pro
• DeepSeek Chat v3
• Meta Llama 3.1
• DeepSeek R1
• Qwen Coder
• Mistral Small 3.1
• An extensive selection of further options.

Expedited Deployment Procedure

The simplest pathway to deployment involves executing the provided setup script:

bash

Obtain a local copy of the repository

git clone https://your-repo-url/openrouter-mcp-client.git cd openrouter-mcp-client

Execute the bootstrapping script

node install.cjs

This script automates several steps: 1. Assists in generating the necessary .env configuration file, prompting for your OpenRouter access key. 2. Installs all requisite software dependencies. 3. Compiles the source code (building the project). 4. Outputs instructions for final application integration.

Alternative Manual Setup

For users preferring manual configuration:

bash

Clone the repository source

git clone https://your-repo-url/openrouter-mcp-client.git cd openrouter-mcp-client

Install all dependencies via npm

npm install

Duplicate the template environment file and populate it

cp .env.example .env

Manually edit .env, inserting your OpenRouter API key

Compile the application

npm run build

Environmental Configuration Details

Modify the .env file to specify your OpenRouter authentication token and the preferred default computational engine:

env OPENROUTER_API_KEY=your_api_key_here OPENROUTER_DEFAULT_MODEL=google/gemini-2.5-pro-exp-03-25:free

Retrieve your authorization key from OpenRouter Keys.

Integration into Cursor

To successfully utilize this service within the Cursor IDE, the application's MCP configuration file must be updated:

1. Locate Cursor's Configuration Directory:
2. Windows: %USERPROFILE%\.cursor\

3. macOS/Linux: ~/.cursor/

4. Modify or Create mcp.json: Inject a configuration stanza similar to the following:

{ "mcpServers": { "custom-openrouter-client": { "command": "node", "args": [ "FULL_PATH_TO/openrouter-mcp-client/dist/index.js" ], "env": { "OPENROUTER_API_KEY": "your_api_key_here", "OPENROUTER_DEFAULT_MODEL": "google/gemini-2.5-pro-exp-03-25:free" } } } }

Note: Substitute FULL_PATH_TO with the absolute path to where you installed the client binaries.

1. Restart Cursor to load the new configuration.

2. Activation via Model Selector:

3. Launch Cursor.
4. Invoke the model selection interface (Ctrl+Shift+L on Windows/Linux or Cmd+Shift+L on macOS).
5. Select the newly defined identifier: "custom-openrouter-client".

Verification Testing (Bypassing MCP)

For direct validation of API connectivity, uncomment the corresponding testing routines within src/index.ts:

typescript // Uncomment to test the direct API testDirectApi().catch(console.error); testMultiModelCompletion().catch(console.error);

Execute the application in foreground mode:

bash npm start

Development Workflow

For ongoing development, utilize the file-watching mode for automatic recompilation:

bash

Enable watch mode for continuous development builds

npm run dev

Troubleshooting Common Issues

Node.js Version Incompatibility

Crucial Requirement: This utility mandates Node.js version 18.0.0 or superior. Older versions frequently result in initialization failures or display EBADENGINE warnings. Verify your current installation via:

bash node --version

If outdated, download and install the current Long-Term Support (LTS) release from nodejs.org.

Module System Conflicts (ESM vs. CJS)

Potential conflicts can arise from mixed module formats:

• The primary source code utilizes ECMAScript Modules (indicated by "type": "module" in package.json).
• The installation helper script is written in CommonJS (using the .cjs extension).
• Ensure the bootstrapping script is invoked correctly using node install.cjs.

Cursor Connection Failures

If the IDE fails to interface with the service:

1. Confirm that the file path specified in mcp.json is absolutely correct and uses forward slashes (/).
2. Validate that the project was successfully compiled using npm run build.
3. Double-check the validity of the OpenRouter token within the environment settings.
4. Inspect the Cursor application logs for detailed error reports.

Referenced Documentation

• OpenRouter Service Documentation
• Model Context Protocol Specification
• Cursor IDE Official Site

Deployment via Smithery Platform

This MCP endpoint can be hosted on Smithery to offer centralized access to various consuming AI agents and applications.

Prerequisites for Smithery

• An active GitHub account.
• Your active OpenRouter API token.

Deployment Steps

1. Repository Duplication: Create a personal fork of this repository within your GitHub account.

2. Smithery Login: Access smithery.ai and authenticate using your GitHub credentials.

3. New Server Addition:

4. Navigate to the Smithery control panel and select "Add Server".
5. Point Smithery to your forked repository.

6. Configure the automated build parameters:

   • Set the base working directory to the repository's root level.
   • Verify that the associated Dockerfile and smithery.yaml manifest are correctly recognized.

7. Initiate Deployment:

8. Smithery will automatically commence the build and deployment sequence.
9. Upon completion, the operational MCP server becomes accessible through Smithery's managed registry.

Utilizing the Deployed Server

Once hosted via Smithery, end-users can configure their client connections:

1. Within their chosen MCP client (e.g., Claude or any compatible platform), add the server reference pointing to the Smithery registry endpoint.
2. Users must input their unique OpenRouter API key and specify their preferred default model.
3. The application can then commence utilizing the centralized service for accessing the model fleet.

Comparison: Smithery Hosting Versus Local Execution

• Smithery Hosting: Optimized for broad dissemination; eliminates the requirement for consumers to locally download, configure, or build the client software.
• Local Execution: Superior for personal development, debugging, and maintenance; provides granular control over the immediate execution environment.

Choose the deployment strategy that optimally aligns with your distribution objectives.