openrouter-mcp-server

dubaigit/openrouter-mcp-server

3.2

If you are the rightful owner of openrouter-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The OpenRouter Agent Tools MCP Server is a Model Context Protocol server that connects AI agents on OpenRouter with local system capabilities, allowing intelligent interaction with the system.

Tools
9
Resources
0
Prompts
0

OpenRouter Agent Tools - MCP Server

License: MIT Node.js TypeScript

An MCP (Model Context Protocol) server that bridges AI agents running on OpenRouter with local system capabilities. It exposes file operations, process management, and command execution through the MCP protocol, enabling the x-ai/grok-4.1-fast model to interact with your system intelligently.

Security Warning ⚠️

THIS SERVER PROVIDES DIRECT SYSTEM ACCESS. READ BEFORE USING.

This MCP server grants unrestricted access to:

  • Your entire file system
  • All shell commands with user privileges
  • Running process information
  • Any capability of the running user account

This server is NOT suitable for production or untrusted environments.

For critical security details, file access restrictions, and recommended safeguards, see the .

Features

9 System Tools:

  • 🗂️ File System (6 tools): read_file, write_file, list_directory, create_directory, delete_file, get_file_info
  • ⚙️ Process Management (2 tools): execute_command, list_processes
  • 🤖 AI Integration (1 tool): ask_grok - Query the OpenRouter Grok model with access to all tools

Framework & Integration:

  • Built on mcp-use framework for reliable MCP protocol support
  • Integrated with x-ai/grok-4.1-fast model on OpenRouter
  • TypeScript with full type safety
  • Hot reload development mode with Inspector UI

Quick Start

Prerequisites

  • Node.js 18 or higher
  • npm 8 or higher
  • OpenRouter API key (free tier available)

1. Get an OpenRouter API Key

  1. Visit https://openrouter.ai
  2. Sign up (free) or log in
  3. Go to your API Keys page
  4. Copy your API key (starts with sk-or-v1-)

2. Clone & Install

git clone https://github.com/your-org/openrouter-mcp-server.git
cd openrouter-mcp-server
npm install

3. Configure Environment

cp .env.example .env

Edit .env and add your API key:

OPENROUTER_API_KEY=sk-or-v1-your-actual-api-key-here

4. Start the Server

Development mode (with hot reload):

npm run dev

Production mode:

npm run build
npm start

Expected output:

OpenRouter Agent Tools MCP Server running on port 3000
Inspector available at: http://localhost:3000/inspector

5. Test with Inspector UI

Open http://localhost:3000/inspector in your browser to:

  • Browse all available tools
  • Test tools interactively
  • See responses and error messages
  • Verify your setup is working

Available Tools

File System Tools

ToolDescriptionParameters
read_fileRead file contentspath (string)
write_fileWrite to filepath, content (strings)
list_directoryList directory contentspath (string)
create_directoryCreate new directorypath (string)
delete_fileDelete a filepath (string)
get_file_infoGet file metadata (size, dates)path (string)

Process Tools

ToolDescriptionParameters
execute_commandRun shell commandscommand (string), cwd (optional)
list_processesList running processesNone

AI Agent Tool

ToolDescriptionParameters
ask_grokQuery Grok with tool accessquery (string), system_prompt (optional)

Usage Examples

Example 1: List Files in a Directory

Using Inspector:

  1. Select list_directory tool
  2. Enter path: /tmp
  3. Click Execute

Response: Shows all files and directories in /tmp

Example 2: Use Grok to Create a Report

{
  "query": "Create a file called report.txt in /tmp containing today's date and time, then list all .txt files in /tmp",
  "system_prompt": "You are a helpful assistant. Be concise and accurate."
}

Grok will:

  1. Understand you want to create a file with date/time
  2. Use execute_command to get current date
  3. Use write_file to create the report
  4. Use execute_command or list_directory to find txt files
  5. Return the results

Example 3: Execute a Command Directly

{
  "command": "npm list --depth=0",
  "cwd": "/Users/username/projects/my-app"
}

Testing with claude-mcp-cli

When testing parameterless tools with claude-mcp-cli, you must provide an empty object:

# Correct: Provide empty object for parameterless tools
claude-mcp-cli -s openrouter-agent tool call get_agent_history -i '{}'
claude-mcp-cli -s openrouter-agent tool call list_active_tasks -i '{}'
claude-mcp-cli -s openrouter-agent tool call clear_agent_history -i '{}'

# Incorrect: Omitting -i flag will cause validation error
claude-mcp-cli -s openrouter-agent tool call get_agent_history
# Error: Invalid input: expected record, received null

Why? The MCP specification requires empty objects {} for tools without parameters. Some CLI tools send null instead, causing validation errors. This is expected behavior per the MCP spec.

Note: This limitation only affects CLI testing. When used from Claude Code/Desktop, these tools work correctly without any special handling.

Testing Tools with Parameters

# execute_task_autonomously requires task parameter
claude-mcp-cli -s openrouter-agent tool call execute_task_autonomously -i '{"task": "Calculate 2 + 2"}'

# get_task_status requires taskId parameter
claude-mcp-cli -s openrouter-agent tool call get_task_status -i '{"taskId": "some-task-id"}'

Known Limitations

The execute_task_autonomously tool requires Claude Code's sampling capability and cannot be tested via claude-mcp-cli. Test this tool directly from Claude Code instead.

See for comprehensive test results including validation, error handling, and concurrent request testing.

Architecture Overview

┌────────────────────────────────────┐
│    Your Application / CLI          │
└────────────────┬───────────────────┘
                 │ (MCP Protocol)
┌────────────────▼───────────────────┐
│   OpenRouter MCP Server            │
│                                    │
│  ┌──────────────────────────────┐  │
│  │  File System Tools (6)       │  │
│  │  Process Tools (2)           │  │
│  │  OpenRouter Integration (1)  │  │
│  └──────────────────────────────┘  │
└────────────────┬───────────────────┘
                 │ (HTTPS)
         ┌───────▼────────┐
         │ OpenRouter API │
         │  Grok 4.1 Fast │
         └────────────────┘

How it works:

  1. You send queries to the ask_grok tool
  2. The server sends your query to OpenRouter with tool definitions
  3. Grok analyzes your request and decides which tools to use
  4. Grok returns its reasoning and the tools it would call (or can execute them)
  5. You get back the results

Development

Run Tests

npm test              # Run all tests once
npm run test:watch   # Run tests in watch mode

Build for Production

npm run build

Outputs to dist/ directory.

Available Scripts

npm run dev       # Development with hot reload
npm run build     # Build for production
npm start         # Run production build
npm test          # Run tests once
npm test:watch   # Run tests in watch mode
npm run deploy    # Deploy (if configured)

Documentation

  • - Detailed documentation, security warnings, configuration, troubleshooting, and examples
  • OpenRouter API Docs - OpenRouter API reference
  • MCP Protocol - Model Context Protocol specification
  • - Development plan and task breakdown

Configuration

Environment variables (create .env from .env.example):

# Required
OPENROUTER_API_KEY=sk-or-v1-...        # Your OpenRouter API key

# Optional
PORT=3000                               # Server port (default: 3000)
MCP_URL=http://localhost:3000          # Base URL for MCP server
OPENROUTER_REFERER=http://localhost:3000  # Referer for OpenRouter
NODE_ENV=development                    # development or production

Troubleshooting

Port Already in Use

PORT=3001 npm run dev

API Key Error

Ensure .env file exists with valid OPENROUTER_API_KEY

Permission Denied Errors

Check file permissions and ensure the server process has access to the paths you're trying to use

For more troubleshooting help, see

Project Structure

openrouter-mcp-server/
├── index.ts                          # Main MCP server entry point
├── src/
│   ├── openrouter-client.ts          # OpenRouter API client
│   ├── tools/
│   │   ├── filesystem.ts             # File system tool implementations
│   │   ├── filesystem.test.ts        # File system tests
│   │   ├── process.ts                # Process tool implementations
│   │   └── process.test.ts           # Process tests
│   └── openrouter-client.test.ts     # Client tests
├── docs/
│   ├── USAGE.md                      # Complete usage documentation
│   └── plans/
│       └── 2025-12-08-openrouter-agent-tools.md  # Implementation plan
├── .env.example                      # Environment template
├── package.json                      # Dependencies
├── tsconfig.json                     # TypeScript config
└── README.md                         # This file

License

MIT - See LICENSE file for details

Support & Feedback

  • Check the documentation first
  • Review the
  • Report issues on GitHub with:
    • Clear description of the problem
    • Steps to reproduce
    • Error messages (sanitized of API keys)
    • OS and Node.js version

Happy building! Start the server and open the Inspector at http://localhost:3000/inspector to begin exploring the tools.