Ask Scientist

Summary

Ask Scientist is a local stdio MCP server for rate-limited questions to a specialized scientist. It uses OpenAI gpt-5.5-pro, includes OpenAI web search, and defaults to 3 accepted questions per 6-hour sliding window. The quota limit and window length are configurable.

1. how to install

Claude

1. Download ask-scientist-<version>.mcpb from the latest GitHub Release.
2. Install the .mcpb file in Claude Desktop.
3. Enter your OpenAI API key and state directory when prompted.

Codex

1. Export your OpenAI API key in the shell that starts Codex:

   export OPENAI_API_KEY=REPLACE_WITH_OPENAI_API_KEY

2. Add this server to ~/.codex/config.toml:

   [mcp_servers.ask_scientist]
   command = "npx"
   args = ["-y", "@micka33/ask-scientist@latest"]
   env_vars = ["OPENAI_API_KEY"]
   
   [mcp_servers.ask_scientist.env]
   ASK_SCIENTIST_STATE_DIR = "/Users/you/.ask-scientist"
   ASK_SCIENTIST_QUOTA_LIMIT = "3"
   ASK_SCIENTIST_QUOTA_WINDOW_HOURS = "6"

3. Restart Codex, then use /mcp to confirm the server is available.

Cursor

1. Open Cursor's MCP configuration, usually ~/.cursor/mcp.json.

2. Add the server:

   {
     "mcpServers": {
       "ask_scientist": {
         "command": "npx",
         "args": ["-y", "@micka33/ask-scientist@latest"],
         "env": {
           "OPENAI_API_KEY": "REPLACE_WITH_OPENAI_API_KEY",
           "ASK_SCIENTIST_STATE_DIR": "/Users/you/.ask-scientist",
           "ASK_SCIENTIST_QUOTA_LIMIT": "3",
           "ASK_SCIENTIST_QUOTA_WINDOW_HOURS": "6"
         }
       }
     }
   }

3. Save the file and restart Cursor.

For more install detail, see INSTALL.md.

2. Tools

• ask_scientist_instant: asks a question and polls up to 20 minutes.
• ask_scientist_deferred: submits a one-request Batch API job.
• check_scientist_request: checks an instant or deferred request.
• get_scientist_quota: shows remaining quota and reset time.

Only accepted instant/deferred questions consume quota.

3. Configuration

Required:

• OPENAI_API_KEY
• ASK_SCIENTIST_STATE_DIR

Optional:

• ASK_SCIENTIST_MODEL, default gpt-5.5-pro
• ASK_SCIENTIST_INSTANT_TIMEOUT_MS, default 1200000
• ASK_SCIENTIST_QUOTA_LIMIT, default 3
• ASK_SCIENTIST_QUOTA_WINDOW_HOURS, default 6

For example, to allow 3 accepted questions per 24 hours:

[mcp_servers.ask_scientist.env]
ASK_SCIENTIST_QUOTA_LIMIT = "3"
ASK_SCIENTIST_QUOTA_WINDOW_HOURS = "24"

Keep MCP config files private. Direct config storage can expose API keys to the local client configuration and launched server environment.

4. Development

npm install
npm run check

The test suite uses fake OpenAI clients and does not make live API calls.

Release tags named v<package-version> publish the npm package and attach a versioned .mcpb file to the GitHub Release.