Skip to content
/ valyu-claude-agent-sdk Public

Give your Claude AI agents access to real-time web data and specialized knowledge with Valyu's DeepSearch API. Add powerful search capabilities to Claude in just a few lines of code. Works seamlessly with the Claude Agent SDK.

1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

GhouI/valyu-claude-agent-sdk

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
queries
queries
 
 
tools
tools
 
 
types
types
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
main.ts
main.ts
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
test-all.ts
test-all.ts
 
 

Repository files navigation

Valyu MCP Tools for Claude Agent SDK

Give your Claude AI agents access to real-time web data and specialized knowledge with Valyu's DeepSearch API. Add powerful search capabilities to Claude in just a few lines of code. Works seamlessly with the Claude Agent SDK.

Installation

npm install --legacy-peer-deps

Note: Use --legacy-peer-deps due to Zod version compatibility requirements.

Quick Start

Get started with web search in seconds:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuWebSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "What are the latest developments in AI?",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-web-search__web_search"],
    mcpServers: {
      "valyu-web-search": valyuWebSearchServer,
    },
  },
})) {
  // Handle messages
}

That's it! Get your free API key from the Valyu Platform - $10 in free credits when you sign up.

Need Specialized Search?

Beyond general web search, Valyu provides domain-specific tools for specialized research:

  • financeSearch - Stock prices, earnings, market data
  • paperSearch - Academic papers, arXiv, scholarly articles
  • bioSearch - Medical research, clinical trials, PubMed
  • patentSearch - Patent databases, prior art, inventions
  • secSearch - SEC filings, 10-K, 10-Q, regulatory documents
  • economicsSearch - BLS, FRED, World Bank economic indicators
  • companyResearch - Comprehensive company intelligence reports

Table of Contents

Setup

  1. Get your API key from the Valyu Platform
  2. Add it to your .env file:
VALYU_API_KEY=your-api-key-here

That's it! The package reads it automatically.

Available Tools

webSearch

Search the web for current information, news, articles, and general content.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuWebSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "What happened in AI tech news last week?",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-web-search__web_search"],
    mcpServers: {
      "valyu-web-search": valyuWebSearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: Real-time information, news, current events, general web content

financeSearch

Search financial data including stock prices, market data, earnings reports, and financial metrics.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuFinanceSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "What are Apple's latest earnings?",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-finance-search__finance_search"],
    mcpServers: {
      "valyu-finance-search": valyuFinanceSearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: Stock prices, earnings reports, financial statements, market data, economic indicators

Data Sources: valyu/valyu-stocks, valyu/valyu-sec-filings, valyu/valyu-earnings-US, valyu/valyu-balance-sheet-US, valyu/valyu-income-statement-US, valyu/valyu-cash-flow-US, valyu/valyu-dividends-US, valyu/valyu-insider-transactions-US, valyu/valyu-market-movers-US, valyu/valyu-crypto, valyu/valyu-forex, valyu/valyu-bls, valyu/valyu-fred, valyu/valyu-world-bank

paperSearch

Search academic research papers, scholarly articles, and textbooks across all disciplines.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuPaperSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "Find recent research on transformer neural networks",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-paper-search__paper_search"],
    mcpServers: {
      "valyu-paper-search": valyuPaperSearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: Academic research, scientific papers, scholarly articles, arXiv papers

Data Sources: valyu/valyu-arxiv, valyu/valyu-biorxiv, valyu/valyu-medrxiv, valyu/valyu-pubmed

bioSearch

Search biomedical literature including PubMed articles, clinical trials, and FDA drug information.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuBioSearchServer, createBioSearchServer } from "./tools/index.js";

// Using default configuration
for await (const message of query({
  prompt: "Find clinical trials for cancer immunotherapy",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-bio-search__bio_search"],
    mcpServers: {
      "valyu-bio-search": valyuBioSearchServer,
    },
  },
})) {
  // Handle messages
}

// Using custom configuration
const customBioSearch = createBioSearchServer({
  searchType: "proprietary",
  maxNumResults: 10,
  includedSources: ["valyu/valyu-pubmed", "valyu/valyu-clinical-trials"],
  maxPrice: 100,
  relevanceThreshold: 0.7,
  category: "clinical-trials",
});

for await (const message of query({
  prompt: "Find clinical trials for cancer immunotherapy",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-bio-search__bio_search"],
    mcpServers: {
      "valyu-bio-search": customBioSearch,
    },
  },
})) {
  // Handle messages
}

Best for: Medical research, clinical trials, drug information, disease studies, FDA labels

Data Sources: valyu/valyu-pubmed, valyu/valyu-biorxiv, valyu/valyu-medrxiv, valyu/valyu-clinical-trials, valyu/valyu-drug-labels

patentSearch

Search patent databases for inventions, innovations, and intellectual property.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuPatentSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "Find patents related to quantum computing",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-patent-search__patent_search"],
    mcpServers: {
      "valyu-patent-search": valyuPatentSearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: Patent information, prior art, inventions, intellectual property

Data Sources: valyu/valyu-patents

secSearch

Search SEC filings including 10-K, 10-Q, 8-K, and other regulatory documents.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuSecSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "Find Tesla's latest 10-K filing",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-sec-search__sec_search"],
    mcpServers: {
      "valyu-sec-search": valyuSecSearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: SEC filings, annual reports, quarterly reports, proxy statements, regulatory disclosures

Data Sources: valyu/valyu-sec-filings

economicsSearch

Search economic data including labor statistics, Federal Reserve data, World Bank indicators, and US federal spending.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuEconomicsSearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "What is the current US unemployment rate?",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-economics-search__economics_search"],
    mcpServers: {
      "valyu-economics-search": valyuEconomicsSearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: Labor statistics (BLS), Federal Reserve economic data (FRED), World Bank indicators, unemployment rates, GDP, inflation, government spending

Data Sources: valyu/valyu-bls, valyu/valyu-fred, valyu/valyu-world-bank, valyu/valyu-worldbank-indicators, valyu/valyu-usaspending

companyResearch

Generate comprehensive company intelligence reports with business overview, financials, SEC filings, news, insider activity, and citations.

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuCompanyResearchServer } from "./tools/index.js";

for await (const message of query({
  prompt: "Research Apple Inc",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-company-research__company_research"],
    mcpServers: {
      "valyu-company-research": valyuCompanyResearchServer,
    },
  },
})) {
  // Handle messages
}

Best for: In-depth company research, due diligence, competitive intelligence, investment research. Automatically gathers data in parallel from multiple sources and synthesizes into a structured markdown report. Supports optional section filtering (summary, leadership, products, funding, competitors, filings, financials, news, insiders).

Note: This tool uses the Valyu Answer API which provides AI-synthesized responses with citations. Costs are controlled via the dataMaxPrice parameter (default: $1.00 per section).

Configuration Options

The bioSearch tool supports custom configuration via createBioSearchServer():

import { createBioSearchServer } from "./tools/index.js";

const customServer = createBioSearchServer({
  // Search type: "proprietary" (premium sources) or "web" (default: "proprietary")
  searchType: "proprietary",

  // Maximum number of results (default: 5)
  maxNumResults: 10,

  // Specific data sources to search
  includedSources: [
    "valyu/valyu-pubmed",
    "valyu/valyu-clinical-trials",
  ],

  // Maximum price per query in CPM (cost per thousand retrievals)
  maxPrice: 100,

  // Relevance threshold (0-1) to filter results by quality
  relevanceThreshold: 0.7,

  // Category to focus the search on
  category: "clinical-trials",
});

Examples

Multi-Tool Search

Combine multiple search tools for comprehensive research:

import { query } from "@anthropic-ai/claude-agent-sdk";
import {
  valyuPaperSearchServer,
  valyuBioSearchServer,
  valyuFinanceSearchServer,
} from "./tools/index.js";

for await (const message of query({
  prompt: "Research the commercialization of CRISPR technology",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: [
      "mcp__valyu-paper-search__paper_search",
      "mcp__valyu-bio-search__bio_search",
      "mcp__valyu-finance-search__finance_search",
    ],
    mcpServers: {
      "valyu-paper-search": valyuPaperSearchServer,
      "valyu-bio-search": valyuBioSearchServer,
      "valyu-finance-search": valyuFinanceSearchServer,
    },
  },
})) {
  // Handle messages
}

Running Individual Queries

Each tool has a dedicated query file in the queries/ directory:

# Run bio search
node --loader ts-node/esm queries/bio-search-query.ts

# Run company research
node --loader ts-node/esm queries/company-research-query.ts

# Run economics search
node --loader ts-node/esm queries/economics-search-query.ts

Or use the main.ts file with your preferred example:

# Edit main.ts to uncomment the example you want
npm start

TypeScript Support

Full TypeScript types included:

import {
  valyuBioSearchServer,
  createBioSearchServer,
} from "./tools/index.js";
import type { ValyuBioSearchConfig } from "./types/index.js";

const config: ValyuBioSearchConfig = {
  searchType: "proprietary",
  maxNumResults: 10,
  relevanceThreshold: 0.7,
};

const customServer = createBioSearchServer(config);

Available Types

  • ValyuBaseConfig - Base configuration for all tools
  • ValyuWebSearchConfig - Web search configuration
  • ValyuFinanceSearchConfig - Finance search configuration
  • ValyuPaperSearchConfig - Research paper search configuration
  • ValyuBioSearchConfig - Biomedical search configuration
  • ValyuPatentSearchConfig - Patent search configuration
  • ValyuSecSearchConfig - SEC filings search configuration
  • ValyuEconomicsSearchConfig - Economics search configuration
  • ValyuCompanyResearchConfig - Company research configuration
  • ValyuSearchResult - Individual search result
  • ValyuApiResponse - API response structure

Tool Naming Convention

All MCP tools follow this naming pattern:

  • Server name: valyu-{tool-name}
  • Tool name: {tool_name}
  • Full identifier: mcp__valyu-{tool-name}__{tool_name}

Examples:

  • Bio Search: mcp__valyu-bio-search__bio_search
  • Finance Search: mcp__valyu-finance-search__finance_search
  • Company Research: mcp__valyu-company-research__company_research

Project Structure

.
├── tools/                      # MCP tool definitions
│   ├── biosearch.ts
│   ├── company-research.ts
│   ├── economics-search.ts
│   ├── finance-search.ts
│   ├── paper-search.ts
│   ├── patent-search.ts
│   ├── sec-search.ts
│   ├── web-search.ts
│   └── index.ts               # Exports all servers
├── queries/                   # Individual query files
│   ├── bio-search-query.ts
│   ├── company-research-query.ts
│   ├── economics-search-query.ts
│   ├── finance-search-query.ts
│   ├── paper-search-query.ts
│   ├── patent-search-query.ts
│   ├── sec-search-query.ts
│   └── web-search-query.ts
├── types/                     # TypeScript type definitions
│   └── index.ts
├── main.ts                    # Main entry point with examples
├── test-all.ts               # Test suite for all tools
├── package.json
└── .env                       # API keys (not committed)

Links

Features

  • Multiple Specialized Tools: Eight domain-specific tools including seven search tools and one comprehensive research tool
  • Premium Data Sources: Access to academic papers (arXiv), biomedical research (PubMed), financial data, patents, SEC filings, economic indicators (BLS, FRED, World Bank), and AI-powered company intelligence
  • Real-time Search: Get current information from across the web
  • Flexible Configuration: Control costs, relevance thresholds, and data sources
  • Type-Safe: Full TypeScript support with detailed type definitions
  • Easy Integration: Works seamlessly with Claude Agent SDK
  • Generous Free Tier: $10 in free credits when you sign up
  • Model Context Protocol: Built using MCP standards for Claude agents

Cost Control

Valyu uses a CPM (cost per thousand retrievals) pricing model. Control your costs with:

import { createBioSearchServer } from "./tools/index.js";

const costControlledServer = createBioSearchServer({
  maxPrice: 100,              // Maximum cost per query (CPM)
  maxNumResults: 5,           // Limit number of results
  relevanceThreshold: 0.8,    // Only high-quality results
});

Dependencies

  • @anthropic-ai/claude-agent-sdk: ^0.1.42
  • dotenv: ^17.2.3
  • zod: ^3.24.1

License

MIT

Built with Valyu DeepSearch API - Powering Claude AI agents with comprehensive search capabilities.

About

Give your Claude AI agents access to real-time web data and specialized knowledge with Valyu's DeepSearch API. Add powerful search capabilities to Claude in just a few lines of code. Works seamlessly with the Claude Agent SDK.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages