npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

omaha-mcp

v1.0.0

Published

MCP server for the Omaha Insights Public API

Readme

omaha-mcp

MCP server for the Omaha Insights Public API. Exposes three tools:

| Tool | Description | | ----------------------- | --------------------------------------------------------------- | | search_financial_data | Query time-series financial metrics for companies | | search_companies | Look up company profiles by ID or ISIN | | search_metrics | Discover available metric slugs and their supported frequencies |

Table of contents

  1. Prerequisites
  2. Build
  3. Configure Claude Code CLI
  4. Configure Claude Desktop
  5. Test with MCP Inspector
  6. Test manually via stdin/stdout
  7. Using the tools
  8. Example prompts
  9. Environment variables
  10. Publishing & distribution
  11. Versioning & maintenance
  12. Troubleshooting

1. Prerequisites

  • Node.js 20+
  • A valid Omaha Insights API key (MEMBER or ADMIN role)

2. Build

npm install
npm run build

3. Configure Claude Code CLI

Run this once from any directory:

claude mcp add omaha -s user \
  -e OMAHA_API_KEY=your-key-here \
  -e OMAHA_BASE_URL=https://api.omaha-insights.app \
  -- node /path/to/omaha-mcp/dist/index.js
  • -s user registers the server globally (available in every project)
  • -e passes environment variables to the server process

Verify the server is registered and connected:

claude mcp list
# omaha: node /path/to/omaha-mcp/dist/index.js ✓ connected

Remove or update the server:

claude mcp remove omaha -s user

Rebuild (npm run build) after any source change, then restart Claude Code.


4. Configure Claude Desktop

Open (or create) the Claude Desktop config file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add the mcpServers block alongside any existing keys:

{
  "mcpServers": {
    "omaha": {
      "command": "node",
      "args": ["/path/to/omaha-mcp/dist/index.js"],
      "env": {
        "OMAHA_API_KEY": "your-key-here",
        "OMAHA_BASE_URL": "https://api.omaha-insights.app"
      }
    }
  }
}

Restart Claude Desktop after saving. The three Omaha tools will appear in the tool picker.

Rebuild (npm run build) after any source change — Claude Desktop does not hot-reload the server.


5. Test with MCP Inspector

The MCP Inspector is a browser-based UI that lets you call tools directly without involving Claude. It is the fastest way to verify the server works.

OMAHA_API_KEY=your-key-here npx @modelcontextprotocol/inspector node dist/index.js

This opens a browser tab (usually http://localhost:5173).

What to check:

  1. Tools tab — three tools should appear: search_metrics, search_companies, search_financial_data.
  2. Call search_metrics with an empty input {} — should return a list of all available metrics and a metadata object.
  3. Call search_companies with a known ISIN, e.g. { "isins": ["US0378331005"] }.
  4. Call search_financial_data using a companyId and metric slug returned by the previous calls.

A successful response looks like:

{
  "data": [ ... ],
  "metadata": {
    "total": 42,
    "page": 1,
    "pageLimit": 1000,
    "pageCount": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

An auth failure returns:

{
  "content": [{ "type": "text", "text": "API error (401): ..." }],
  "isError": true
}

6. Test manually via stdin/stdout

Check it starts

OMAHA_API_KEY=your-key-here node dist/index.js

The process should hang silently — that is correct behaviour for a stdio MCP server. Press Ctrl+C to exit.

Missing key error

node dist/index.js
# Error: OMAHA_API_KEY environment variable is required.
# (exits with code 1)

Send a raw JSON-RPC request

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | OMAHA_API_KEY=your-key-here node dist/index.js

Expected output:

{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search_financial_data",...},{"name":"search_companies",...},{"name":"search_metrics",...}]}}

7. Using the tools

Claude calls the tools automatically when relevant. The typical call sequence is:

User asks for data
      │
      ▼
search_metrics          ← discover valid slug (if unknown)
      │
      ▼
search_companies        ← resolve ISIN → companyId
      │
      ▼
search_financial_data   ← fetch the actual data

Key behaviours to be aware of:

  • startDate/endDate format depends on frequency: ISO string ("2024-01-01") for daily/weekly, numeric year (2020) for yearly.
  • Results are paginated at 1,000 rows/page. Claude should show you metadata.hasNextPage and ask before fetching more.
  • Your organisation has a daily cap of 20,000 unique company IDs. Avoid bulk loops without explicit confirmation.
  • search_metrics filtering is an exact slug match — if the result is empty, try a different slug variant.
  • All requests time out after 15 seconds. If the API is unreachable you will get "Request timed out after 15s" instead of a silent hang.

Ranking queries

When you ask for top/bottom N companies by a metric (e.g. "top 10 by EROI in 2023"), Claude will:

  1. Warn you about quota consumption and ask for confirmation
  2. Show you the total number of companies and estimated cost
  3. Only proceed after your explicit confirmation
  4. Paginate through all companies, batch by 20, aggregate and rank the results

8. Example prompts

Work through these in order — each step builds on the previous one and exercises a different part of the server.

Step 1 — verify the tools are available

List the Omaha Insights tools you have access to.

You should see search_metrics, search_companies, and search_financial_data listed.

Step 2 — discover metrics

What financial metrics are available in Omaha Insights? Show me the first page.
Is there a metric for EBITDA? What frequencies does it support?

Claude calls search_metrics. Note the metadata.total in the response — that's how many metrics exist in total.

Step 3 — look up a company

Find the Omaha Insights profile for Apple using ISIN US0378331005.

Claude calls search_companies and returns the full profile including the internal companyId. Copy that ID — you'll use it in the next steps.

Step 4 — fetch financial data (yearly)

Get the yearly EROI for Apple from 2018 to 2023.

Claude calls search_financial_data with frequency: "yearly" and should pass startDate: 2018 and endDate: 2023 as numbers, not strings.

Step 5 — fetch financial data (daily)

Get Apple's daily total_equity values between 2024-01-01 and 2024-03-31.

Claude should now pass startDate: "2024-01-01" as an ISO string. This tests the date format duality.

Step 6 — test pagination awareness

Fetch all available metrics and tell me the total count.

Claude should report metadata.total and metadata.hasNextPage, then ask before fetching page 2. It should not auto-paginate.

Step 7 — test error handling

Get financial data for company 99999999 using metric "fake_metric".

Should surface a clear API error message, not a crash.

Step 8 — test ranking (quota warning)

Give me the top 10 companies by EROI in 2023.

Claude should warn about quota consumption and ask for confirmation before proceeding.


9. Environment variables

| Variable | Required | Default | | ---------------- | -------- | -------------------------------- | | OMAHA_API_KEY | Yes | — | | OMAHA_BASE_URL | No | https://api.omaha-insights.app |

To point at a local or staging server:

"env": {
  "OMAHA_API_KEY": "your-key-here",
  "OMAHA_BASE_URL": "http://localhost:3000"
}

10. Publishing & distribution

The recommended way to distribute this server to clients is as an npm package. This removes the need for clients to clone the repo or run a build step.

Publish to npm

npm publish --access public
# or for a scoped private package:
npm publish --access restricted

Consider scoping the package name, e.g. @omaha-insights/mcp, to avoid naming conflicts.

Client setup (after publishing)

The client only needs to:

  1. Get an API key from Omaha Insights.
  2. Add one block to their Claude Desktop config (claude_desktop_config.json) or run one claude mcp add command:

Claude Desktop:

{
  "mcpServers": {
    "omaha": {
      "command": "npx",
      "args": ["-y", "@omaha-insights/mcp"],
      "env": {
        "OMAHA_API_KEY": "their-key-here"
      }
    }
  }
}

Claude Code CLI:

claude mcp add omaha -s user \
  -e OMAHA_API_KEY=their-key-here \
  -- npx -y @omaha-insights/mcp

npx -y downloads and runs the latest version automatically — no install step needed.

Pinning to a version

If a client wants stability over automatic updates, they can pin to a major version:

"args": ["-y", "@omaha-insights/mcp@1"]

11. Versioning & maintenance

This package follows semantic versioning.

What triggers each version bump

| Change | Version bump | Example | |---|---|---| | Bug fix, no behaviour change | Patch (1.0.x) | Fix wrong orderBy value | | New tool, new optional parameter | Minor (1.x.0) | Add a fourth endpoint | | Renamed parameter, removed tool, broken behaviour | Major (x.0.0) | Rename companyIds → ids |

API changes that don't affect the MCP schema — new metrics, new company data, updated values — require no MCP release.

When to cut a new release

Update this package when the public API:

  • Adds a new endpoint → add a new tool (minor bump)
  • Changes an enum value (e.g. orderBy options) → patch or major depending on whether old values still work
  • Changes the response envelope structure → patch or major
  • Changes date format expectations → major bump, update tool descriptions

Maintenance checklist for each release

  1. Update the tool description text if behaviour or constraints changed.
  2. Update the Zod schema if input fields changed.
  3. Update OMAHA_BASE_URL default in src/index.ts if the production URL changed.
  4. Bump the version in package.json.
  5. Tag the release on GitHub and update the CHANGELOG.
  6. Run npm publish.

Areas most likely to drift

These parts of the MCP are tightly coupled to the API and should be reviewed when the API changes:

  • orderBy enum values in search_companies ("isin" / "id")
  • startDate / endDate format rules (ISO string vs. numeric year)
  • The daily quota cap (20,000 unique company IDs) mentioned in tool descriptions

12. Troubleshooting

Tools don't appear in Claude Desktop

  1. Confirm claude_desktop_config.json is valid JSON (no trailing commas).
  2. Confirm the path in args exists: ls /Users/romain/Developer/omaha-mcp/dist/index.js
  3. Restart Claude Desktop fully (quit from menu bar, not just close the window).
  4. Check server logs: Claude Desktop → Settings → Developer → MCP Servers → omaha → Show logs.

401 Unauthorized

The API key is wrong, expired, or the account lacks MEMBER/ADMIN role. Re-check OMAHA_API_KEY in the config.

429 Too Many Requests

Rate limit hit (10 requests / 60 seconds). Wait a minute and retry.

Request timed out after 15s

The API did not respond within 15 seconds. Check that OMAHA_BASE_URL is correct and the server is reachable. Retry the request — transient network issues resolve on their own.

Yearly date passed as a string

If you get a validation error on startDate/endDate with frequency: "yearly", Claude passed "2020" (string) instead of 2020 (number). Prompt it:

Pass startDate and endDate as plain numbers for yearly frequency, not strings.