ryddle/any-api-mcp

ANY API MCP Server

An MCP (Model Context Protocol) server designed to interact with any API that exposes an OpenAPI v3 specification. The server dynamically parses the OpenAPI spec and exposes the API endpoints as tools usable by AI assistants.

Features

• Compatible with any API: Just provide your API's OpenAPI spec file.
• Multiple authentication methods: Supports the most common auth systems.
• Flexible configuration: Via JSON file or environment variables.
• Dynamic tool generation: Automatically converts endpoints into MCP tools.

Architecture

The project is built using the following technologies and patterns:

• Node.js & TypeScript: The runtime environment and base language.
• Model Context Protocol (MCP) SDK: Uses @modelcontextprotocol/sdk to implement the MCP server over stdio.
• Modular Authentication System: Adapter-based architecture supporting multiple authentication types.
• Dynamic Tool Generation: Reads the OpenAPI file and converts each operation into an MCP Tool.

Prerequisites

• Node.js (v16 or higher)
• The API to expose must be network accessible.
• Your API's OpenAPI spec file (JSON or YAML).

Installation and Build

1. Install dependencies:

   npm install
   

2. Compile the TypeScript code:

   npm run build
   

Configuration

Configuration can be done in two ways:

Option 1: Configuration file (Recommended)

Create a config.json file in the project root:

{
  "apiUrl": "https://api.example.com",
  "openApiSpecPath": "./open-api.json",
  "serverName": "my-api-mcp",
  "serverVersion": "1.0.0",
  "auth": {
    "type": "bearer-endpoint",
    "endpoint": "/auth/token",
    "method": "POST",
    "body": {
      "key": "${API_KEY}",
      "secret": "${API_SECRET}"
    },
    "tokenPath": "token"
  }
}

See config.example.json for more configuration examples.

Option 2: Environment variables

Create a .env file in the project root:

API_URL=http://localhost:8080/api
AUTH_TYPE=bearer-endpoint
AUTH_ENDPOINT=/auth/token
AUTH_TOKEN_PATH=token
API_KEY=your_api_key
API_SECRET=your_api_secret

Supported Authentication Types

1. No Authentication (none)

{
  "auth": {
    "type": "none"
  }
}

2. HTTP Basic Auth (basic)

{
  "auth": {
    "type": "basic",
    "username": "myuser",
    "password": "mypassword"
  }
}

3. API Key (api-key)

Supports sending via header, query param, or cookie:

{
  "auth": {
    "type": "api-key",
    "keyName": "X-API-Key",
    "keyValue": "your-api-key",
    "location": "header",
    "prefix": ""
  }
}

4. Static Bearer Token (bearer-token)

For tokens that don't expire or are managed externally:

{
  "auth": {
    "type": "bearer-token",
    "token": "your-static-bearer-token"
  }
}

5. Bearer Token from Endpoint (bearer-endpoint)

Obtains the token from an authentication endpoint:

{
  "auth": {
    "type": "bearer-endpoint",
    "endpoint": "/auth/token",
    "method": "POST",
    "body": {
      "key": "${API_KEY}",
      "secret": "${API_SECRET}"
    },
    "tokenPath": "token",
    "expiresIn": 3600
  }
}

Note: Use ${VAR_NAME} to reference environment variables in the body.

6. OAuth2 Client Credentials (oauth2-client-credentials)

{
  "auth": {
    "type": "oauth2-client-credentials",
    "tokenUrl": "https://auth.example.com/oauth/token",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scopes": ["read", "write"],
    "credentialsInBody": false
  }
}

Environment Variables

Usage in MCP Clients

To use this server in tools like Claude Desktop or VS Code extensions that support MCP:

{
  "mcpServers": {
    "any-api": {
      "command": "node",
      "args": ["/absolute/path/to/any-api-mcp/build/index.js"]
    }
  }
}

Make sure to replace /absolute/path/to/any-api-mcp/ with the actual path where you cloned this repository.

Extending the Authentication System

To add a new authentication type:

1. Create a new adapter in src/auth/adapters/ that extends BaseAuthAdapter
2. Add the new type to AuthType in src/auth/types.ts
3. Create the corresponding configuration interface
4. Register the adapter in AuthFactory.createAdapter() in src/auth/factory.ts

Development

To make changes to the server:

1. Modify the code in src/.
2. Recompile with npm run build.
3. Restart your MCP client to reload the changes.