Metadata-Version: 2.4
Name: mcp-everything
Version: 0.4.0
Summary: 18 plug-and-play MCP servers for Claude — Hacker News, Wikipedia, Weather, GitHub, Reddit, and more. One install, zero hassle.
Author: mcp-everything contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/mcp-everything
Project-URL: Issues, https://github.com/yourusername/mcp-everything/issues
Keywords: mcp,claude,anthropic,model-context-protocol,ai,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.5.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: packaging>=23.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

# mcp-everything

> **18 plug-and-play MCP servers for Claude — one install, zero hassle.**

[![PyPI version](https://badge.fury.io/py/mcp-everything.svg)](https://badge.fury.io/py/mcp-everything)
[![CI](https://github.com/yourusername/mcp-everything/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/mcp-everything/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

---

**mcp-everything** is a single Python package that ships real, working [MCP servers](https://modelcontextprotocol.io) — not just a list of links. Install once, run the setup wizard, restart Claude Desktop, and you're done.

```bash
pip install mcp-everything
mcp-everything setup
```

That's it. Claude can now browse Hacker News, search Wikipedia, look up weather, pull GitHub issues, search Reddit, fetch research papers, and more — all without leaving the conversation.

---

## Servers

| Server | Tools | API Key? | What you can ask Claude |
|--------|-------|----------|-------------------------|
| **Hacker News** | 4 | ✅ None | *"What's trending on HN today?"*, *"Search HN for posts about Rust"* |
| **Wikipedia** | 4 | ✅ None | *"Summarise the Wikipedia article on black holes"* |
| **ArXiv** | 3 | ✅ None | *"Find recent papers on LLM reasoning"* |
| **Weather** | 2 | ✅ None | *"What's the weather in Tokyo?"*, *"7-day forecast for London"* |
| **Reddit** | 4 | ✅ None | *"What are the hot posts on r/MachineLearning?"* |
| **Pokédex** | 3 | ✅ None | *"What are Charizard's stats?"*, *"What beats Dragon types?"* |
| **Crypto** | 4 | ✅ None | *"What's Bitcoin's price?"*, *"What crypto is trending today?"* |
| **Countries** | 3 | ✅ None | *"Tell me about Japan"*, *"Compare Germany and France"* |
| **Books** | 4 | ✅ None | *"Find books by Ursula Le Guin"*, *"What's trending on Open Library?"* |
| **Recipes** | 4 | ✅ None | *"Give me a random recipe"*, *"Find pasta recipes"* |
| **Dictionary** | 2 | ✅ None | *"Define 'ephemeral'"*, *"Synonyms for 'happy'"* |
| **Translate** | 2 | ✅ None | *"Translate 'good morning' into Japanese"* |
| **Public Holidays** | 3 | ✅ None | *"What's the next UK public holiday?"* |
| **GitHub** | 5 | 🔑 Free token | *"Search GitHub for FastMCP examples"* |
| **News** | 3 | 🔑 Free tier | *"Top tech news today"*, *"Search news for AI regulation"* |
| **NASA** | 3 | 🔑 Free (or DEMO_KEY) | *"Show me today's Astronomy Picture of the Day"*, *"Any asteroids near Earth?"* |
| **Movies & TV** | 4 | 🔑 Free (TMDB) | *"What movies are trending?"*, *"Top rated TV shows of all time"* |
| **YouTube** | 3 | 🔑 Free (Google) | *"Search YouTube for Python tutorials"*, *"What's trending in the US?"* |

> **13 of 18 servers work with zero API keys.** `mcp-everything setup` will only ask for keys when you actually enable a server that needs one.

---

## Quick Start

### 1. Install

```bash
pip install mcp-everything
```

### 2. Run the setup wizard

```bash
mcp-everything setup
```

The wizard will:
- Show you all available servers in a nice table
- Let you pick which ones to enable (`all`, `free`, or `1,2,5`)
- Prompt for API keys **only** for servers you enable that need them
- Auto-detect your Claude Desktop config path (macOS / Windows / Linux)
- Write the config and tell you to restart Claude

### 3. Restart Claude Desktop

That's it. You'll see your new MCP servers connected in Claude.

---

## Manual Install (without the wizard)

If you'd rather configure manually, add servers to your `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "mcp_everything.servers.hackernews"]
    },
    "wikipedia": {
      "command": "python",
      "args": ["-m", "mcp_everything.servers.wikipedia"]
    },
    "weather": {
      "command": "python",
      "args": ["-m", "mcp_everything.servers.weather"]
    },
    "github": {
      "command": "python",
      "args": ["-m", "mcp_everything.servers.github"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}
```

---

## CLI Reference

```bash
# Setup & management
mcp-everything setup          # interactive setup wizard
mcp-everything list           # show all available servers
mcp-everything add <server>   # add a single server (e.g. mcp-everything add hackernews)
mcp-everything remove <server># remove a server
mcp-everything status         # show which servers are currently active

# Dashboard & config
mcp-everything serve          # open web dashboard at localhost:7337
mcp-everything export         # export your config as a shareable JSON file (keys excluded)
mcp-everything import <file>  # import a config shared by someone else

# Tooling
mcp-everything create <name>  # scaffold a new custom server from a template
mcp-everything test [server]  # fire live API calls and show pass/fail + response times
mcp-everything doctor         # full diagnostics: Python, config, API keys, imports
mcp-everything update         # check PyPI for a newer version
```

---

## Web Dashboard

`mcp-everything serve` opens a local web UI at **[localhost:7337](http://localhost:7337)** — no terminal required.

From the dashboard you can:
- Toggle servers on/off with a single click
- Enter and save API keys securely (stored in `~/.mcp-everything/.env`, not in your Claude config)
- Run live connection tests against any server
- See which servers are active at a glance

---

## API Key Storage

API keys are stored in `~/.mcp-everything/.env` rather than inside `claude_desktop_config.json`. This means:

- **More secure** — keys live in a dedicated directory with clear ownership
- **Easier to edit** — one plain-text file, not buried in a JSON config
- **Shareable configs** — `mcp-everything export` produces a key-free JSON anyone can import

The `.env` file is created automatically the first time you add a key (via `setup` or the web dashboard).

---

## Server Details

### Hacker News
No API key needed. Uses the [official HN Firebase API](https://github.com/HackerNews/API) + Algolia search.

| Tool | Description |
|------|-------------|
| `hn_top_stories` | Get current top stories (up to 30) |
| `hn_search` | Full-text search via Algolia |
| `hn_get_comments` | Get top comments for any story ID |
| `hn_ask_hn` | Get current "Ask HN" posts |

### Wikipedia
No API key needed. Uses the [Wikipedia REST API](https://en.wikipedia.org/api/rest_v1/).

| Tool | Description |
|------|-------------|
| `wikipedia_search` | Search for articles |
| `wikipedia_summary` | Get concise article summary |
| `wikipedia_random` | Get a random article |
| `wikipedia_on_this_day` | Historical events for any date |

### ArXiv
No API key needed. Uses the [ArXiv public API](https://info.arxiv.org/help/api/).

| Tool | Description |
|------|-------------|
| `arxiv_search` | Search papers by keyword + optional category |
| `arxiv_recent` | Latest papers in a category (e.g. `cs.AI`) |
| `arxiv_get_paper` | Full metadata for a paper ID or URL |

### Weather
No API key needed. Uses [Open-Meteo](https://open-meteo.com/) — free, no registration, no rate limits.

| Tool | Description |
|------|-------------|
| `weather_current` | Current conditions for any city |
| `weather_forecast` | 1–14 day forecast |

### Reddit
No API key needed. Uses Reddit's public JSON endpoints.

| Tool | Description |
|------|-------------|
| `reddit_hot` | Hot posts in any subreddit |
| `reddit_search` | Search across Reddit |
| `reddit_top` | Top posts by time period |
| `reddit_comments` | Read top comments from a post |

### Pokédex
No API key needed. Uses [PokéAPI](https://pokeapi.co/).

| Tool | Description |
|------|-------------|
| `pokedex_get` | Pokémon stats by name or number |
| `pokedex_move` | Move details (power, accuracy, PP) |
| `pokedex_type_matchup` | Type effectiveness chart |

### GitHub
Free API token from [github.com/settings/tokens](https://github.com/settings/tokens). Read-only public access is enough. Without a token, GitHub allows 60 unauthenticated requests/hour (still works for light use).

| Tool | Description |
|------|-------------|
| `github_search_repos` | Search repositories by keyword |
| `github_get_repo` | Full repo metadata |
| `github_list_issues` | Open/closed issues for any repo |
| `github_search_code` | Search code across GitHub |
| `github_trending` | Top-starred repos, optionally by language |

### News (NewsAPI)
Free API key from [newsapi.org/register](https://newsapi.org/register). Free tier: 100 requests/day, developer use only.

| Tool | Description |
|------|-------------|
| `news_headlines` | Top headlines by country + category |
| `news_search` | Search news articles |
| `news_sources` | List available news sources |

---

## Adding a New Server (Contributing)

Each server is a self-contained Python file using [FastMCP](https://github.com/modelcontextprotocol/python-sdk):

```python
# mcp_everything/servers/myserver.py
from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("myserver")

@mcp.tool()
async def my_tool(query: str) -> str:
    """Description Claude will see. Args are auto-documented.

    Args:
        query: What to search for
    """
    # your implementation
    return "result"

if __name__ == "__main__":
    mcp.run()
```

Then add an entry to the `SERVERS` list in `mcp_everything/config.py` and open a PR. That's genuinely all it takes — we'd love more servers!

See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

---

## Roadmap

- [ ] **Spotify** — now playing, search, playback control
- [ ] **Wolfram Alpha** — math, science, data queries
- [ ] **Jira / Linear** — issue tracking
- [ ] **Slack** — search messages (via MCP)
- [ ] Single-file installer script (no Python required)

Have a server you'd love to see? [Open an issue](https://github.com/yourusername/mcp-everything/issues).

---

## Requirements

- Python 3.10+
- [Claude Desktop](https://claude.ai/download) (macOS, Windows, or Linux)

---

## License

MIT — do whatever you want with it. A ⭐ star is always appreciated.
