typesearch MCP server

News search for AI agents, as an MCP server: recent news on any topic from outlets worldwide, each result with a calibrated relevance score, by country and language.

This package is the local server (npx -y typesearch-mcp, stdio). The same tools are also served remotely at https://api.typesearch.ai/mcp, with nothing to install. Both need a typesearch API key and bill like the API.

In Cursor, replace YOUR_TYPESEARCH_API_KEY in the configuration it adds; VS Code asks for the key.

Tools

Every tool is read-only. Missing an outlet? Suggest it from the dashboard (Suggest a source) or write to support@typesearch.ai. Results are compact to save your agent's tokens: readable text for the model plus the same data as structuredContent. Calls are billed to your key at the API's prices; the tool descriptions state them.

Related MCP server: news-sentiment-mcp

Plugins

This repository is also a plugin for Claude Code, Cursor and Gemini CLI: the remote server plus a news-search skill that tells the agent when to use each tool and how to pick a mode, a time window, countries and languages. Each one asks for your API key once and keeps it as a secret.

# Claude Code
claude plugin marketplace add typesearch-ai/typesearch-mcp
claude plugin install typesearch@typesearch

# Gemini CLI
gemini extensions install https://github.com/typesearch-ai/typesearch-mcp

In Cursor, install typesearch from the Cursor Marketplace.

Set it up

Claude Code

# Remote
claude mcp add --transport http typesearch https://api.typesearch.ai/mcp --header "Authorization: Bearer $TYPESEARCH_API_KEY"

# Local
claude mcp add typesearch --env TYPESEARCH_API_KEY=$TYPESEARCH_API_KEY -- npx -y typesearch-mcp

Codex

# Local
codex mcp add typesearch --env TYPESEARCH_API_KEY=$TYPESEARCH_API_KEY -- npx -y typesearch-mcp

Or, for the remote server, in ~/.codex/config.toml:

[mcp_servers.typesearch]
url = "https://api.typesearch.ai/mcp"
bearer_token_env_var = "TYPESEARCH_API_KEY"

Claude Desktop, Cursor, Windsurf and other clients

Add the server to the client's MCP configuration (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json…):

{
  "mcpServers": {
    "typesearch": {
      "command": "npx",
      "args": ["-y", "typesearch-mcp"],
      "env": { "TYPESEARCH_API_KEY": "YOUR_TYPESEARCH_API_KEY" }
    }
  }
}

Clients that take a remote URL with headers can use https://api.typesearch.ai/mcp with Authorization: Bearer YOUR_TYPESEARCH_API_KEY (Windsurf: "serverUrl" and "headers"). Clients that only accept a URL can pass the key in it: https://api.typesearch.ai/mcp?typesearchApiKey=YOUR_TYPESEARCH_API_KEY — treat that URL as a secret.

Docker

docker build -t typesearch-mcp .
docker run -i --rm -e TYPESEARCH_API_KEY typesearch-mcp

Configuration

Node 20 or later. The package is a single file with no dependencies, so npx -y typesearch-mcp starts quickly.

Development

npm ci
npm test                # builds dist/index.js and runs the tools against a fake API, in memory and over stdio
npm run inspect         # opens the MCP Inspector on the built server
npm run compare-remote  # checks that tools/list and the instructions match https://api.typesearch.ai/mcp

The tool parameters, titles, descriptions, annotations, server instructions and output format live in src/contrato/mcp-contrato.ts: a verbatim copy of the contract of the remote server, so both list and answer exactly the same. npm run sync-contract refreshes it from the API repository (TYPESEARCH_API_DIR); the tests fail if the copy is edited by hand.

Built with the official MCP TypeScript SDK and typesearch-js, bundled into dist/index.js.

License

MIT