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
- Prerequisites
- Build
- Configure Claude Code CLI
- Configure Claude Desktop
- Test with MCP Inspector
- Test manually via stdin/stdout
- Using the tools
- Example prompts
- Environment variables
- Publishing & distribution
- Versioning & maintenance
- Troubleshooting
1. Prerequisites
- Node.js 20+
- A valid Omaha Insights API key (MEMBER or ADMIN role)
2. Build
npm install
npm run build3. 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 userregisters the server globally (available in every project)-epasses 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 ✓ connectedRemove or update the server:
claude mcp remove omaha -s userRebuild (
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.jsonAdd 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.jsThis opens a browser tab (usually http://localhost:5173).
What to check:
- Tools tab — three tools should appear:
search_metrics,search_companies,search_financial_data. - Call
search_metricswith an empty input{}— should return a list of all available metrics and ametadataobject. - Call
search_companieswith a known ISIN, e.g.{ "isins": ["US0378331005"] }. - Call
search_financial_datausing acompanyIdand 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.jsThe 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.jsExpected 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 dataKey behaviours to be aware of:
startDate/endDateformat 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.hasNextPageand ask before fetching more. - Your organisation has a daily cap of 20,000 unique company IDs. Avoid bulk loops without explicit confirmation.
search_metricsfiltering 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:
- Warn you about quota consumption and ask for confirmation
- Show you the total number of companies and estimated cost
- Only proceed after your explicit confirmation
- 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, andsearch_financial_datalisted.
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 themetadata.totalin 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_companiesand returns the full profile including the internalcompanyId. 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_datawithfrequency: "yearly"and should passstartDate: 2018andendDate: 2023as 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.totalandmetadata.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 restrictedConsider scoping the package name, e.g. @omaha-insights/mcp, to avoid naming conflicts.
Client setup (after publishing)
The client only needs to:
- Get an API key from Omaha Insights.
- Add one block to their Claude Desktop config (
claude_desktop_config.json) or run oneclaude mcp addcommand:
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/mcpnpx -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.
orderByoptions) → 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
- Update the tool description text if behaviour or constraints changed.
- Update the Zod schema if input fields changed.
- Update
OMAHA_BASE_URLdefault insrc/index.tsif the production URL changed. - Bump the version in
package.json. - Tag the release on GitHub and update the CHANGELOG.
- 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:
orderByenum values insearch_companies("isin"/"id")startDate/endDateformat 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
- Confirm
claude_desktop_config.jsonis valid JSON (no trailing commas). - Confirm the path in
argsexists:ls /Users/romain/Developer/omaha-mcp/dist/index.js - Restart Claude Desktop fully (quit from menu bar, not just close the window).
- 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.