OpenAI MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with OpenAI's Files, Vector Stores, Assistants, Threads, Messages, and Runs APIs. This server enables Claude Desktop and other MCP clients to manage OpenAI resources and execute assistant conversations directly through natural language.

41 comprehensive tools covering the complete OpenAI Assistants API workflow including file management, vector store operations, assistant configuration, and full conversation execution.

Usage

Use with any MCP-compatible client like Claude/Cursor/VS Code. Add the following configuration to your MCP settings:

{
  "mcpServers": {
    "openai": {
      "command": "npx",
      "args": ["-y", "openai-mcp-tools"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace your_api_key_here with your OpenAI API key.

Available Tools

Files API (5 tools)

• upload_file - Upload files to OpenAI for use with Assistants and Fine-tuning
• list_files - List all files in your organization with optional filtering
• get_file - Retrieve detailed information about a specific file
• delete_file - Delete files from OpenAI
• download_file_content - Download and retrieve file contents

Vector Stores API (14 tools)

• create_vector_store - Create vector stores for semantic search
• list_vector_stores - List all vector stores with pagination
• get_vector_store - Get vector store details
• update_vector_store - Update vector store configuration
• delete_vector_store - Delete vector stores
• add_file_to_vector_store - Add files to vector stores
• list_vector_store_files - List files in a vector store
• remove_file_from_vector_store - Remove files from vector stores
• get_vector_store_file - Get file details in a vector store
• get_vector_store_file_content - Get parsed content from vector store
• create_vector_store_file_batch - Batch add up to 500 files
• get_vector_store_file_batch - Get batch operation status
• cancel_vector_store_file_batch - Cancel in-progress batch
• list_vector_store_file_batch_files - List files in a batch
• search_vector_store - Direct semantic search in vector stores

Assistants API (6 tools)

• create_assistant - Create AI assistants with file search capabilities
• list_assistants - List all assistants
• get_assistant - Get assistant details
• update_assistant - Update assistant configuration
• delete_assistant - Delete assistants
• attach_vector_store_to_assistant - Attach vector stores to assistants for knowledge retrieval

Threads API (4 tools)

• create_thread - Create conversation threads for assistants
• get_thread - Retrieve thread details
• update_thread - Update thread metadata and tool resources
• delete_thread - Delete conversation threads

Messages API (5 tools)

• create_message - Add user or assistant messages to threads
• list_messages - List conversation history in a thread
• get_message - Retrieve specific message details
• update_message - Update message metadata
• delete_message - Remove messages from threads

Runs API (7 tools)

• create_run - Execute an assistant on a thread
• create_thread_and_run - Create thread and run assistant in one call
• list_runs - List all runs for a thread
• get_run - Check run status and details
• update_run - Update run metadata
• cancel_run - Cancel an in-progress run
• submit_tool_outputs - Submit tool call results to continue execution

Development

Local Setup

1. Prerequisite:

   • Node.js v18+
   • npm v9+

2. Clone the repository:

git clone <repo>
cd openai-mcp-tools

3. Install dependencies:

npm install

4. Build the project:

npm run build

Testing

npm run inspector  # Opens MCP Inspector

Error Handling

The server provides detailed error messages for common issues:

• Missing API Key: Clear instructions on how to set the OPENAI_API_KEY
• OpenAI API Errors: Includes status code, message, and request ID for debugging
• File Errors: Helpful messages for file not found, permission errors, etc.

All errors are logged to stderr (safe for stdio transport) and returned to the client in a structured format.

Important Notes

Security Considerations

• Never commit your .env file or expose your OpenAI API key
• The API key is passed via environment variables for security
• File paths are validated to prevent directory traversal attacks

Rate Limits

This server respects OpenAI's API rate limits. The client is configured with:

• 60-second timeout for file uploads
• 2 automatic retries for failed requests

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - feel free to use this in your own projects!

Resources

• Model Context Protocol Documentation
• OpenAI API Documentation
• Claude Desktop

Support

For issues related to:

• This MCP server: Open an issue in this repository
• OpenAI API: Check OpenAI's documentation
• MCP protocol: See MCP documentation