value-investing-agent

English | 中文

Value Investing Agent

An AI-powered MCP server for value investors. Analyze stocks using principles from Benjamin Graham and Warren Buffett. Every value investor deserves their own AI agent.

"Price is what you pay. Value is what you get." - Warren Buffett

Disclaimer

This tool is for educational and research purposes only. It does not constitute investment advice. Investing involves risks, including the potential loss of principal. The author is not responsible for any investment decisions made based on this tool.

Features

• 📊 Real-time Stock Data - Quotes, financials, and company profiles
• 🧮 Intrinsic Value Calculation - DCF model and Graham Number
• 🏰 Moat Analysis - Evaluate competitive advantages
• 📰 News Aggregation - Stay informed on your watchlist
• 📝 Report Generation - Daily summaries and deep analysis reports
• 🔌 Pluggable Data Sources - Easy to add your own data providers

Quick Start

Prerequisites

• Node.js >= 18.0.0
• Any MCP-compatible client (Claude Desktop, Claude Code, or your own application)

Note: This is a standalone MCP server that can run on Windows, macOS, or Linux. It can be used with any application that supports the Model Context Protocol, not just Claude products.

Installation

Option 1: npx (Recommended)

No installation required. Configure MCP directly:

{
  "mcpServers": {
    "value-investing-agent": {
      "command": "npx",
      "args": ["-y", "value-investing-agent"]
    }
  }
}

Option 2: Global Install

npm install -g value-investing-agent

Configure MCP:

{
  "mcpServers": {
    "value-investing-agent": {
      "command": "value-investing-agent"
    }
  }
}

Option 3: From Source

git clone https://github.com/danielchu97/Value-Investing-Agent.git
cd Value-Investing-Agent
npm install
npm run build

Configure MCP:

{
  "mcpServers": {
    "value-investing-agent": {
      "command": "node",
      "args": ["/path/to/value-investing-agent/dist/index.js"]
    }
  }
}

Configuration Files

Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Usage

Get Stock Quote

"Get me the current quote for Apple"
"What's the price of MSFT?"

Analyze Intrinsic Value

"Calculate the intrinsic value of AAPL"
"What is Amazon's fair value using DCF?"

Evaluate Economic Moat

"Analyze the competitive moat of Coca-Cola"
"Does Microsoft have a wide moat?"

Manage Watchlist

"Add GOOGL to my watchlist in the Technology group"
"Show my watchlist"
"Remove TSLA from watchlist"

Generate Reports

"Generate a daily report for my watchlist"
"Create a detailed analysis report for Berkshire Hathaway"

Available Tools

Tool	Description
get_stock_quote	Get real-time stock quote and metrics
get_financials	Fetch financial statements (income, balance, cash flow)
calculate_intrinsic_value	DCF and Graham valuation with margin of safety
analyze_moat	Evaluate competitive advantages
get_news	Get stock-related news articles
manage_watchlist	Manage your personal stock watchlist
generate_daily_report	Daily summary of watchlist stocks
generate_stock_report	Comprehensive value investing analysis
set_provider	Switch data provider
list_providers	List available data providers

Data Providers

The plugin architecture allows you to add your own data sources. See Custom Provider Guide.

Built-in Providers

Provider	API Key	Rate Limit	Best For
yahoo-finance (default)	Not required	Limited (may hit 429 errors)	Quick testing
finnhub	Required (free)	60 calls/min	Production use
alpha-vantage	Required (free)	5 calls/min	Basic data needs

Configuring API Keys

Finnhub (Recommended for reliable access):

• Get free API key at finnhub.io/register
• Set environment variable:

  export FINNHUB_API_KEY=your_api_key_here
  

  Or in Claude Desktop config:

  {
    "mcpServers": {
      "value-investing-agent": {
        "command": "npx",
        "args": ["-y", "value-investing-agent"],
        "env": {
          "FINNHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

Alpha Vantage:

• Get free API key at alphavantage.co
• Set environment variable: ALPHA_VANTAGE_API_KEY=your_key

Switching Providers

"Switch to finnhub provider"
"Use alpha-vantage for data"
"List available providers"

Adding a Custom Provider

• Copy src/providers/provider-template.ts
• Implement the DataProvider interface
• Register in src/providers/index.ts

import { MyProvider } from './my-provider';
registerProvider('my-provider', (config) => new MyProvider(config));

Value Investing Principles

This tool is built on timeless investment principles:

1. Intrinsic Value

A company's true worth based on future cash flows, not market price.

2. Margin of Safety

Buy only when price is significantly below intrinsic value (25%+ discount).

3. Economic Moat

Seek durable competitive advantages that protect profits.

4. Circle of Competence

Only invest in businesses you understand.

5. Mr. Market

Use market emotions as opportunities, don't be ruled by them.

Key Metrics

Valuation

• P/E Ratio: < 15 (undervalued)
• P/B Ratio: < 1.5 (undervalued)
• Graham Number: Price ceiling for defensive investors

Profitability

• ROE: > 15% (excellent)
• Gross Margin: > 40% (pricing power)
• Net Margin: > 10% (efficient)

Safety

• Current Ratio: > 1.5 (liquid)
• Debt/Equity: < 1.0 (conservative)
• Interest Coverage: > 5x (safe)

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Run tests
npm test

# Lint
npm run lint

Project Structure

value-investing-agent/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server
│   ├── providers/            # Data providers
│   ├── tools/                # MCP tools
│   ├── analysis/             # Analysis engine
│   ├── utils/                # Utilities
│   ├── config/               # Configuration
│   └── types/                # TypeScript types
├── skills/                   # Claude skills
├── data/                     # Local data (watchlist, cache)
├── docs/                     # Documentation
└── tests/                    # Test files

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

• Fork the repository
• Create a feature branch
• Make your changes
• Run tests
• Submit a pull request

License

MIT License - see LICENSE for details.

Acknowledgments

This project is inspired by the investment wisdom of:

• Benjamin Graham - The Intelligent Investor, Security Analysis
• Warren Buffett - Berkshire Hathaway Letters to Shareholders
• Charlie Munger - Poor Charlie's Almanack

Resources

• The Intelligent Investor by Benjamin Graham
• Berkshire Hathaway Letters
• Value Investing Guide

Remember: "The stock market is designed to transfer money from the active to the patient." - Warren Buffett